agentstatelabs/AgentStateDeveloper

# AgentStateDeveloper 为 Agent 编写的代码提供代码级上下文和审计覆盖层。 ASD 为每个函数提供一个决策账本、一个效果声明和一个 调用图 —— 所有这些都可以由编写代码的 Agent 进行查询，并且 全部提交到 git 中，因此它们会随每次克隆而传播。 **套件的一部分：** ASD（开发者专属代码上下文）与 **[CTXone](https://github.com/ctxone/ctxone)**（团队共享记忆）配对使用。安装 其中一个时会提供另一个 —— 参见 [与 CTXone 配对](#pairs-with-ctxone)。 ## 安装 ### macOS / Linux — Homebrew（推荐） ``` brew tap agentstatelabs/agentstatedeveloper brew trust agentstatelabs/agentstatedeveloper # one-time, third-party-tap trust brew install asd ``` 安装 `asd`、`asd-mcp` 和 `asd-serve`。通过 `brew upgrade asd` 进行升级。 ### macOS / Linux — 单行命令 ``` curl -fsSL https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/install.sh | sh ``` 将三个二进制文件放入 `~/.local/bin`。可选覆盖项： `ASD_VERSION=v1.2.0`、`INSTALL_DIR=/usr/local/bin`。 ### Windows — PowerShell ``` iwr https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/install.ps1 | iex ``` 将 `asd.exe`、`asd-mcp.exe` 和 `asd-serve.exe` 安装到 `%LOCALAPPDATA%\asd\bin` 并将其添加到您的用户 `PATH` 中。在安装后 打开一个新的 PowerShell 以使新 PATH 生效。 ### 从源码构建（需要 Rust 工具链） ``` cargo install --path crates/agentstatedeveloper-cli # installs asd cargo install --path crates/agentstatedeveloper-mcp # installs asd-mcp + asd-serve ``` ### 卸载 ``` curl -fsSL https://raw.githubusercontent.com/agentstatelabs/AgentStateDeveloper/main/uninstall.sh | sh # 或者： brew uninstall asd ``` ## 功能说明 | 原语 | 您的收益 | |---|---| | **决策账本** | 为任何符号追加决策、隐患、依据和约束。条目在重命名后依然存在。支持批准、拒绝或撤回。 | | **效果声明** | 17 个类别（`io.fs.read`、`io.net.out`、`io.db.write` 等）。按符号声明，并通过调用图传递性传播。 | | **语义索引** | 每个由 tree-sitter 解析的函数、方法和类。支持 9 种语言：Python、TypeScript、Rust、Go、Java、C#、Ruby、Kotlin、Swift。 | | **调用图** | 模块内和跨模块的边。传递效果自动传播。 | | **策略门禁** | 基于文件的 JSON 规则：按操作和参与者类型进行允许、拒绝或需要批准。 | | **批准机制** | 批准、拒绝或撤回账本条目。完整的批准工作流。 | | **审计事件流** | 哈希链式 JSONL 日志，记录每一次账本变更和策略评估。 | | **Git 原生辅助文件** | 已提交的、紧凑的账本条目子集（决策、隐患、方案、映射、分类、跟进事项、Agent 思考）存在于 `.asd/conclusions/*.jsonl` 中 —— 提交到 git，随每次克隆传播。是千字节，而不是兆字节。 | ## 与 CTXone 配对 ASD 和 **[CTXone](https://github.com/ctxone/ctxone)** 作为一个套件构建： - **ASD** —— 开发者专属的**代码上下文**：面向您面前的代码提供决策账本、效果 声明、调用图和影响分析。 - **CTXone** —— **团队层**：在整个团队中共享的决策、计划和记忆。 各自均可独立运行，但结合使用效果更佳： - 安装其中任何一个都会**提示设置另一个** —— 一次性、可关闭的 提醒（使用 `--no-nudge` 或 `ASD_NO_SUGGEST=1` 抑制）。 - 当两者都安装后，`asd skill` 还会安装一个**组合套件技能**， 该技能会教导 Agent 联合工作流：使用 ASD 处理代码细节 （影响、不变量），并将您的决策记录到 CTXone 中，以便团队 继承。 - `asd bootstrap` 会提示安装**两者**。 ## 快速开始 ``` # Clone 和 build git clone https://github.com/agentstatelabs/AgentStateDeveloper.git cd AgentStateDeveloper cargo install --path crates/agentstatedeveloper-cli cargo install --path crates/agentstatedeveloper-mcp # 初始化你的项目 cd my-project asd init asd index . # 读取一个 symbol asd read payments.chargeCard # Append 一个 ledger 条目 asd ledger append payments.chargeCard \ --kind hazard \ --summary "fails silently above 10000 — caller must check return value" \ --author-kind human \ --author-id alice@example.com # 用你的 agent 工具注册 MCP server asd mcp install # Export 已 committed 的 sidecar 并 commit asd conclusions export git add .asd/conclusions/ git commit -m "chore: sync ASD sidecar" ``` （`asd init` 的 pre-commit 钩子会自动运行 `asd conclusions export`； 上面显式的两步操作仅用于说明正在发生的事情。） ### MCP ↔ CLI 命名参考 ASD 有两个具有两种命名约定的接口：MCP 使用扁平 命名空间（`ledger_append`、`code_search`），因此工具不会与其他 MCP 服务器发生冲突；而 CLI 使用嵌套方式（`asd ledger append`、`asd search`）。 规范的映射位于 [docs/mcp-cli-mapping.md](docs/mcp-cli-mapping.md) 中。 这两种形式在 CLI 上都适用 —— 接受过旧版 MCP 时代文档训练的 Agent 可以 输入 `asd ledger append`，也可以（通过 Plan D t-003 中的 clap 别名） 输入等效的 `asd code_search` / `asd callers_of` 等。 ### 面向 Agent 的简要输出模式 `asd` 默认输出详细的 JSON 格式，这对人类和 结构化解析流水线很有帮助，但会消耗 Agent 很少需要的 token。 设置 `ASD_FORMAT=brief`（或在每次调用时传入 `--brief`），将 `read` / `callers` / `callees` 的响应投射为仅包含核心字段 （qname、file:line、签名、文档第一行）。通常在这些 命令上能减少：60–80% 的消耗。 建议在任何驱动 `asd` 的 Agent 进程启动时执行一次此操作： ``` export ASD_FORMAT=brief ``` 适用于 CLI 和 MCP。生成的 `asd-mcp` 服务器在启动时从 其父进程继承 `ASD_FORMAT=brief`，并通过 相同的紧凑格式投射三个调用量最大的读取工具（`code_read`、`code_search`、 `references`）。 ## Agent 设置 ASD 通过几个层级接入您的编码 Agent。最快的途径是让 Agent 自行设置。 ### 粘贴给您的 Agent（推荐） ``` asd bootstrap ``` 打印出一个简短的文本块，您可以将其粘贴到您正在使用的任何 Agent 中（Claude Code、Cursor、Codex、Gemini CLI 等）。然后 Agent 会自行安装、索引 并连接 ASD —— 并且也会提议设置 **CTXone**（团队层）。 ### 单独命令 | 命令 | 设置内容 | |---|---| | `asd mcp install` | 在检测到的每个 Agent 的 MCP 配置中注册 `asd-mcp` stdio 服务器 —— Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI、Windsurf、Zed、VS Code、Cline、Kilo Code、Antigravity 等。重启工具以激活。 | | `asd skill` | 将 ASD 的 **Agent 技能**（`SKILL.md`）安装到每个宿主的 skills 目录中 —— 教导 Agent *何时*使用 ASD。带有版本戳，并且不会覆盖磁盘上较新的技能。当存在 `ctx` CLI 时，它还会安装组合的 **ASD + CTXone** 套件技能。 | | `asd mcp instructions` | 将一个受管理的、常驻的使用说明块注入到 `AGENTS.md` / `CLAUDE.md` 中（幂等 —— 重复运行是安全的）。 | | `asd watch` | 监控代码仓库并在源代码更改时重新索引，因此索引永远不会悄无声息地漂移。 | ``` asd mcp status # registration status across all tools asd mcp install --tool cursor # one specific tool asd mcp install --db /abs/db # non-default db path asd mcp uninstall # remove from all tools asd skill --status # what's installed, per host asd skill --dry-run # preview without writing ``` MCP 服务器会读取 `ASD_DB`（在 env 块中由 `install` 设置），以便 Agent 始终连接到正确的项目数据库。 ## Git 原生辅助文件 ASD 具有两个磁盘位置和一个 SQLite 内的命名空间。了解 哪个是哪个可以避免意外： | 位置 | 包含内容 | 是否由 git 跟踪？ | 对什么具有权威性？ | |----------|--------------|-----------------|---------------------| | `.asd-state.db` | 实时的 SQLite ASG（索引、调用图、FTS、完整账本、追踪） | **否**（被 gitignore 忽略） | 运行时的一切 | | `.asd/conclusions/*.jsonl` | 紧凑子集：决策、分类、映射、隐患、方案、跟进事项、Agent 思考 | **是** | 全新克隆时需要继承的内容 | | `.asd/v1/`（旧版） | 较旧的详细镜像 —— 已被 `.asd/conclusions/` 取代 | **否**（被 gitignore 忽略） | 残留物；`asd sync` / `asd hydrate` 仍会为了本地调试对其进行读写。不在提交路径上。 | 原则是：**已提交的辅助文件承载判断**（Agent 或 人类必须做出的决策）。**其他一切都是可重新生成的**， 可通过 `asd index .` 从源代码生成，因此被 gitignore 忽略。 **一次性设置：** ``` asd init ``` ``` initialized at ./.asd-state.db .gitignore: updated (.asd-state.db and .asd/v1/ ignored — both are local derived state) ASD git hooks installed (.asd/hooks/): pre-commit trigger: git commit command: asd conclusions export purpose: write committed conclusions (decisions/hazards/recipes/…) to .asd/conclusions/*.jsonl post-merge trigger: git merge / git pull command: asd conclusions import && asd index . purpose: import committed .asd/conclusions/ into local ledger and rebuild index post-checkout trigger: git checkout / git switch command: asd conclusions import && asd index . purpose: sync local db to the checked-out branch's sidecar state core.hooksPath → .asd/hooks (hooks are now active) To skip hook installation: asd init --no-hooks To review hooks later: asd hooks ``` 在 `asd init` 之后，pre-commit 钩子会在每次提交时自动运行 `asd conclusions export` —— 无需手动执行步骤。 **克隆后的引导：** ``` git clone asd init # installs hooks, updates .gitignore asd conclusions import # loads .asd/conclusions/*.jsonl → local ledger asd index . # rebuilds derived semantic index from source asd mcp install # registers asd-mcp with your agent tools ``` ## 索引 ``` asd index . # index current directory asd index . --verbose # show each file as it is processed, list skipped files ``` 标准输出： ``` Indexing 42 files under . … Done. 187 symbols, 187 effects. (12 files skipped — run with -v to list) ``` 无法识别的文件类型（`.yaml`、`.json`、`.md` 等）在标准模式下会被静默跳过， 并在 `--verbose` 模式下显示为 `[skip]`。`skipped` 计数始终包含在 JSON 摘要中。 ## 接口 - **`asd`** —— CLI：导向（`architecture`、`search`、`trust`、`map`），变更准备（`prepare-change`、`impact`、`checklist`、`since`、`investigate`、`annotate-commit`、`task-close`、`test-summary`），账本（`ledger`、`invariant`、`conclusions`、`scratch`、`think`），以及底层命令（`init`、`index`、`sync`、`audit`、`hooks`、`mcp`、`skill`、`watch`） —— 完整集合请参见 [`asd --help`](docs/FEATURES.md) - **`asd-mcp`** —— 向编码 Agent 暴露 63 个工具的 stdio MCP 服务器 - **`asd-serve`** —— HTTP 服务器 + Lens 审查 UI ## MCP 工具 Agent 通过 **63 个 MCP 工具** 访问 ASD，涵盖代码搜索/读取、 调用图、导向（`architecture`、`trust`、`endpoints`、`dead_code`）、影响 和变更分析、决策账本、不变量、效果、结论、 临时记录、Agent 思考、反馈和审计 —— 例如 `code_search`、 `code_read`、`callers`、`callees`、`context_for`、`impact`、`prepare_change`、 `since`、`architecture`、`trust`、`ledger_append`、`invariant_add`、 `effect_declare`、`conclusions_export`、`scratch_write`、`think_speculate`、 `feedback_promote`、`audit_verify`、`reindex`。完整列表见 [docs/FEATURES.md](docs/FEATURES.md#mcp-tools)。 ## 文档 **入门：** - [操作指南](docs/WALKTHROUGH.md) —— 安装 → 日常循环 → 底层运行机制 → 结合使用 ASD + CTXone - [功能与命令参考](docs/FEATURES.md) —— 解释每一个命令、原语和 MCP 工具 - [联合功能](docs/FEDERATION.md) —— 将 ASD 指向多个代码仓库，以实现跨仓库边缘和感知决策的影响分析（`asd repo edges/impact`） **参考：** - [MCP ↔ CLI 映射](docs/mcp-cli-mapping.md) —— 两种命名约定并排展示 - [代码仓库注册表](docs/repo-registry.md) —— 共享的多代码仓库注册表（`asd repo`） - [初始读取提示](docs/initial-read-prompt.md) —— `asd think` / `asd map` 背后的冷启动导向提示 - [与 RTK 配对](docs/PAIRING_WITH_RTK.md) **许可：** - [许可与版本](LICENSING.md) —— 通俗易懂的 BSL-1.1 + OSS / Team / Enterprise 版本说明 ## 许可与版本 ASD 是 **开源的，并提供商业支持**，分为三个版本发布： - **OSS**（此代码仓库） —— 完整的面向开发者的引擎：索引、账本、效果、 调用图、影响分析、不变量、代码仓库内跨服务边缘，以及 Agent 引导。自我托管，无需账号。 - **Team** —— 跨代码仓库层（项目组合架构、跨仓库影响 分析和失效端点分析、团队共享的运行时信心），与 **[CTXone](https://github.com/ctxone/ctxone)** 配对作为团队共享记忆。 - **Enterprise** —— 组织级治理：端点注册表、变更治理 门禁、审计/SIEM 导出、组织仪表板，以及基于 RBAC 的 Agent 推广。 代码采用 **BSL-1.1** 许可，并在每次发布 四年后转换为 **Apache-2.0** 许可 —— 内部使用免费；重新分发托管 销售需要商业许可。完整的通俗语言摘要和版本 细分：**[LICENSING.md](LICENSING.md)**。Team/Enterprise 或商业 问题咨询：[licensing@agentstatelabs.com](mailto:licensing@agentstatelabs.com)。

标签：AI编程助手, IPv6支持, MCP, Rust, SOC Prime, 上下文管理, 云安全监控, 可视化界面, 客户端加密, 开发工具, 网络流量审计, 静态分析