CodeStory

为编码 agent 提供本地代码库落地支持。

**场景。** 你身处一个文件数量超出任何人记忆极限的 repo 中。 Agent 需要修改跨越多个 package 的行为——路由、索引、认证等等——而不是仅在已打开的唯一文件中重命名一个变量。 **任务。** 找到拥有该行为的 symbol，查看谁调用了它，阅读实际运行的源代码，并知道下一步该修改哪里。而不是把 `grep -R` 当作架构来用。 **行动。** CodeStory 将工作区索引到本地 SQLite 图谱中： 包含文件、symbol、调用、import、代码片段、搜索投影以及新鲜度说明。使用 `doctor`、`index`、`ground` 和 `report` 进行本地导航。在 sidecar 报告 `retrieval_mode: "full"` 之后使用 `packet` 和 `search`。 **结果。** 工作从一个你可以打开的文件和行号开始，而不是从 ripgrep 中排名第一的匹配项开始。答案会说明它们使用了什么；缺口会指出何时 index 或 sidecar 已经过时。 ``` flowchart LR Repo["workspace files"] --> Index["index"] Index --> Store["local SQLite graph"] Store --> Local["local: ground, report, files, trail, snippet"] Store --> RetrievalIndex["retrieval index"] RetrievalIndex --> Sidecars["Zoekt + Qdrant + SCIP + llama.cpp"] Sidecars --> AgentSearch["agent: packet, search"] ``` ## 你能得到什么 | 需求 | 使用 | | --- | --- | | “我从哪里开始？” | `doctor`, `index`, `ground`, `report` | | “这个 symbol 影响了什么？” | `symbol`, `trail`, `snippet` | | “发生了什么更改，什么可能会出错？” | `affected` | | “通过引用回答关于 repo 的宏观问题。” | 带有完整 sidecar 的 `packet` | | “根据行为术语、路径、symbol 或字面量查找候选项。” | 带有完整 sidecar 的 `search` | ## 在 Repo 上尝试 在此检出位置，构建 CLI 并将其指向任何 repository： ``` cargo build --release -p codestory-cli CODESTORY_CLI="./target/release/codestory-cli" TARGET_WORKSPACE="/path/to/repo" "$CODESTORY_CLI" doctor --project "$TARGET_WORKSPACE" "$CODESTORY_CLI" setup embeddings --project "$TARGET_WORKSPACE" --dry-run --format json "$CODESTORY_CLI" index --project "$TARGET_WORKSPACE" --refresh full "$CODESTORY_CLI" ground --project "$TARGET_WORKSPACE" --why "$CODESTORY_CLI" report --project "$TARGET_WORKSPACE" --output-file codestory-report.md ``` 在 Windows PowerShell 中，请使用 `.\target\release\codestory-cli.exe`，像 `$env:TARGET_WORKSPACE = "C:\path\to\repo"` 这样的环境变量赋值，以及普通的 Windows 路径。 该路径证明了本地导航的准备就绪。它并不能证明 `packet` 或 `search` 的 sidecar 已准备就绪。 为了获取面向 agent 的 packet/search 证据，请先构建并验证 sidecar： ``` "$CODESTORY_CLI" retrieval bootstrap --project "$TARGET_WORKSPACE" --format json "$CODESTORY_CLI" retrieval index --project "$TARGET_WORKSPACE" --refresh full "$CODESTORY_CLI" retrieval status --project "$TARGET_WORKSPACE" --format json "$CODESTORY_CLI" packet --project "$TARGET_WORKSPACE" --question "what owns request routing?" "$CODESTORY_CLI" search --project "$TARGET_WORKSPACE" --query "request routing" --why ``` 在信任 `packet` 或 `search` 之前，`retrieval status` 必须报告 `retrieval_mode: "full"`。有关针对任务设计的流程，请参阅 [docs/usage.md](docs/usage.md)；有关 sidecar 的设置和修复，请参阅 [docs/ops/retrieval-sidecars.md](docs/ops/retrieval-sidecars.md)。 ## 作为 Agent Skill 安装 将 [`.agents/skills/codestory-grounding`](.agents/skills/codestory-grounding) 复制到你的 skill 目录中。运行 `scripts/setup.sh` 或 `scripts/setup.ps1`。详情请见 [`.agents/skills/codestory-grounding/SKILL.md`](.agents/skills/codestory-grounding/SKILL.md)。 ## 命令 | 任务 | 命令 | | --- | --- | | 缓存健康状态 | `doctor --project ` | | 索引 | `index --project --refresh full` | | 方位确定 | `ground --project --why` | | 结合 sidecar 进行查找 | `search --project --query "..." --why` | | 调用图 | `trail --project --id --story` | | 源码 | `snippet --project --id ` | | 目标 bundle | `context --project --id ` | | 带有 sidecar 的任务 packet | `packet --project --question "..."` | | 持久化读取 | `serve --project --stdio` | ## 语言支持 CodeStory 将基于解析器的图覆盖、结构性收集器、经过回归测试的保真度以及 agent packet/search 的准备情况区分开来。当前的契约记录在 [docs/architecture/language-support.md](docs/architecture/language-support.md) 中。 Python、Java、Rust、JavaScript、TypeScript/TSX、C++、C、Go、Ruby、PHP、C#、Kotlin、Swift、Dart 和 Bash 是经过保真度验证的、基于解析器的图语言。HTML、CSS 和 SQL 使用结构性收集器。 ## 证据 基准测试说明是特定于环境和 repository 的证据。不要将其中一行转化为普遍适用的节省声明。 - 评分卡和注意事项：[docs/testing/benchmark-ledger.md](docs/testing/benchmark-ledger.md) - Repo 规模的耗时历史记录：[docs/testing/codestory-e2e-stats-log.md](docs/testing/codestory-e2e-stats-log.md) - Warm stdio 循环历史记录：[docs/testing/codestory-stdio-warm-loop-stats.md](docs/testing/codestory-stdio-warm-loop-stats.md) - 可重复的带/不带 harness 测试：[`scripts/codestory-agent-ab-benchmark.mjs`](scripts/codestory-agent-ab-benchmark.mjs) ## 文档导航 - 用法：[docs/usage.md](docs/usage.md) - 概念：[docs/concepts/how-codestory-works.md](docs/concepts/how-codestory-works.md) - 架构：[docs/architecture/overview.md](docs/architecture/overview.md) - 语言：[docs/architecture/language-support.md](docs/architecture/language-support.md) - 基准测试：[docs/testing/benchmark-ledger.md](docs/testing/benchmark-ledger.md) - 贡献：[docs/contributors/getting-started.md](docs/contributors/getting-started.md) ## License Apache-2.0。详见 [LICENSE](LICENSE)。

标签：AI编程助手, Rust, SOC Prime, 代码分析, 凭证管理, 可视化界面, 开发工具, 本地大模型, 网络流量审计, 通知系统