microsoft/clarity-agent

# Clarity 代理 一个会提出质疑的AI思考伙伴。 大多数AI工具帮助您更快地执行。Clarity 则通过提出经验丰富的架构师、产品经理和安全工程师会问的问题，帮助您首先弄清楚是否正在构建正确的东西。答案会以人类可读的文档形式记录下来，供您审阅、与团队分享，或导出为Word文档供利益相关者审阅；这些文档也可供代理使用，因此您与Clarity完成的工作成果能够超越任何单一对话的局限。 ``` You: I want to build a real-time collaboration feature for our doc editor. Clarity: Before we design that — what happens when two people edit the same paragraph at the same time? Do you need true real-time (cursors, presence), or is "no one loses work" the actual requirement? Those lead to very different architectures. ``` Clarity 可作为桌面应用、Web界面运行，或嵌入您的编码代理中。它会在您的代码库中生成一个 `.clarity-protocol/` 目录，其中包含捕获您的问题、解决方案、故障分析和决策的人类可读Markdown文件。该清晰度协议会随着项目的发展而保持更新，并像源代码一样进行管理。 [在此博客文章中](https://medium.com/@yonatanzunger/are-we-building-the-right-ai-203cfc7effdc)阅读更多关于Clarity代理背后的理念。 ## 快速开始 ### 安装 **下载桌面应用**（无需终端）： 从 [GitHub Releases 页面](https://github.com/microsoft/clarity-agent/releases/latest) 下载最新的 `.dmg`（macOS）或 `.exe` 安装程序（Windows），直接安装。无任何前提条件。 **或通过脚本安装**（添加 `clarity` CLI 并将Clarity嵌入git仓库）： *macOS / Linux：* ``` curl -fsSL https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.sh | bash ``` *Windows (PowerShell)：* ``` irm https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.ps1 | iex ``` **或克隆并手动安装：* ``` git clone https://github.com/microsoft/clarity-agent.git cd clarity-agent bash scripts/install.sh # macOS / Linux .\scripts\install.ps1 # Windows ``` ### 启动并连接一个LLM **macOS：** 从 `~/Applications` 打开 `Clarity.app`。 **Windows：** 从开始菜单运行已安装的应用，或者如果您使用了脚本安装程序，可从终端运行 `clarity`。 **Linux：** 从终端运行 `clarity`。 首次启动时，设置向导将引导您完成连接LLM提供商的过程。 **支持的提供商：** | 提供商 | 认证选项 | | --- | --- | | **Anthropic (Claude)** | Claude Code 登录 (`claude login`) · 来自 [console.anthropic.com](https://console.anthropic.com/settings/keys) 的 API 密钥 | | **OpenAI (GPT)** | 来自 [platform.openai.com](https://platform.openai.com/api-keys) 的 API 密钥 | | **Azure AI** | Microsoft 登录 · Azure CLI (`az login`) · API 密钥 | | **GitHub Copilot** | GitHub CLI (`gh auth login`) · 个人访问令牌 | | **Google Gemini** | 来自 [Google AI Studio](https://aistudio.google.com/apikey) 的 API 密钥 | Clarity 与前沿模型配合效果最佳——结构化思维是模型质量影响最大的地方。设置向导会在保存凭据之前测试它们。随时运行 `clarity doctor` 可重新检查配置。 ### 开始一个会话 应用会打开项目选择器。创建一个新项目或打开一个现有文件夹。Clarity 会询问您正在做什么，并引导您对问题、解决方案和故障模式进行结构化思考。所有内容都会保存到一个 `.clarity-protocol/` 目录中——无需代码库。 ### 使用方法 **适用于任何类型的项目** — 打开应用，创建一个项目，然后开始交谈。Clarity 会询问您正在做什么，并从那里开始引导您。无需代码库。 **适用于编码项目** — 将Clarity嵌入您的代码库，以便您的编码代理能够识别它： ``` clarity embed /path/to/your-project ``` 这会添加一个 `AGENTS.md` 代码片段和一个 `.clarity-protocol/` 目录。这些是普通的文件，就像代码库中的任何其他文件一样进行管理——在PR中提交、审查和进行差异比较。此后，您的编码代理（Claude Code、Cursor等）会遵循流程指南作为其正常工作流程的一部分。 ## 功能说明 Clarity 引导您进行结构化对话，并将结果实时写入清晰度协议： **问题澄清** — “您要解决什么问题？利益相关者是谁？成功的标准是什么？”推动您将模糊的意图转化为可测试的准则。 **解决方案探索** — “鉴于这个问题，我们该如何解决？”探索各种方法，揭示权衡取舍，并确保解决方案确实能解决该问题。 **故障分析** — 多个AI“思考者”从不同角度（安全、人因、对抗性、运营）独立检查您的系统，然后您与它们一起研究结果：将相关故障分组，追踪因果链条，制定管理计划。 **决策跟踪** — 重要选择会连同其标准、选项和理由一起被记录下来。当上游文档发生变化时，代理知道哪些决策可能需要重新审视。 **陈旧性跟踪** — 文档形成一个依赖关系图。当您的问题陈述发生变化时，Clarity 知道您的解决方案描述可能已经过时，并会提示您重新审视它。 ## 产出内容 一个 `.clarity-protocol/` 目录： ``` .clarity-protocol/ ├── summary.md # Brief summary of what this project is ├── notes.md # Principles and cross-cutting observations ├── observations.md # Patterns and coverage notes from analysis ├── goal/ │ ├── problem.md # What you're trying to achieve and why │ ├── stakeholders.md # Who cares about the outcome │ ├── requirements.md # Criteria any solution must satisfy │ ├── open-questions.md # Unknowns that could change the approach │ └── resolved-questions.md # Questions answered, with findings ├── solution/ │ ├── solution.md # What you plan to build │ ├── architecture.md # How you plan to build it │ └── solution-summary.md # Concise overview for stakeholders ├── failures/ │ └── failures.md # Failure modes, chains, and management plans ├── decisions/ │ └── decisions.md # Decision log with criteria and reasoning └── config.json # Dependency graph and content hashes ``` 人类可读的Markdown，可进行版本控制和差异比较。直接编辑文件，在PR中审查它们，或与未参与对话的协作者分享。生成**审查包**（Markdown或Word格式）供利益相关者审阅。 ## 如何融入您的工作流 - **思考一个问题？** 打开应用并开始交谈。适用于软件、战略、研究、产品决策——任何足够复杂、值得进行结构化思考的事情。 - **开始一个软件项目？** 在编写代码之前使用Clarity。到开始构建时，您将拥有清晰的问题陈述、经过深思熟虑的解决方案以及初步的故障分析。 - **现有代码库？** 在任何git仓库上运行 `clarity embed`。将代理指向您的代码，它将帮助您阐明已有的内容、填补缺失的上下文，并保持协议的更新。 - **团队协作？** `.clarity-protocol/` 目录存放在您的代码库中。每个人都能看到当前状态；当事情发生变化时，代理会跟踪哪些内容已经过时。 - **审阅之前？** 生成审查包，为利益相关者提供连贯的叙述，而不是要求他们阅读原始笔记。 ## 关于AI局限性的说明 Clarity 是一款AI驱动的工具，而AI具有实际的局限性。AI生成的内容可能不正确或不完整。Clarity代理专为对话设计——您应该质疑那些似乎不对的想法，就像它会质疑您的想法一样。质量取决于使用有能力的模型（前沿模型在这里确实有区别）并诚实地回应它提出的问题。 不要依赖AI做出关于健康、金融或法律的重大决策。将Clarity用作思考的场所，而不是人类专业知识的替代品。 有关预期用途、局限性和负责任使用的详细信息，请参阅[负责任AI常见问题解答](AIFAQ.md)。 ## CLI参考 ``` clarity Launch web UI (default) clarity web [project_dir] Headless web server clarity app Launch desktop app clarity cli [project_dir] Interactive terminal session clarity process NAME [project_dir] Run a single process by name clarity packet [project_dir] Generate a review packet clarity embed Wire Clarity into a git repo clarity install [--mode MODE] Install as a desktop app clarity update Update to the latest version clarity doctor Diagnose the installation clarity help Show help ``` ## 设计原则 Clarity 的设计遵循以下原则。 **困难的部分是理解您真正想要什么。** Clarity 做的最有价值的事情不是撰写文档，而是问您正确的问题。文档只是副产品。 **文件优于记忆。** 所有内容都以人类可读的Markdown格式写入磁盘。不存在仅存在于聊天记录或LLM上下文窗口中的内容。 **多视角发现更多故障。** 思考者架构从不同角度运行独立分析，然后综合结果。这反映了安全工程在实践中的工作方式。 **Clarity是迭代的。** 从粗略开始，随着学习不断精炼。依赖关系跟踪器知道何时需要重新审视某些内容。 ## 商标

标签：AI代理, C2, Markdown文档, TCP SYN 扫描, Web UI, 产品管理, 产品设计, 代码集成, 决策支持, 团队协作, 失败模式分析, 安全工程, 安全评审, 开发流程优化, 思考伙伴, 意图提炼, 技术架构, 文档生成, 文档结构分析, 架构设计, 桌面应用, 源代码管理, 编码代理集成, 网络安全研究, 自动化文档, 计划管理, 软件开发辅助, 问题提问, 防御加固, 项目协作, 风险分析