aiflow

aiflow **aiflow 将任何代码仓库转变为受控、AI 驱动的软件交付流程，只需一条命令。** 它将 [Claude Code](https://docs.claude.com/en/docs/claude-code) 与持久的任务跟踪、两层代码内存（结构图 + 语义 RAG）、自主工作循环、专家审查/审计代理、令牌/成本控制、强制代码风格、可配置的 Git 分支模型和一流的团队协作结合起来，以便 AI 代理（或人类 + 代理团队）可以接受任务、计划、编写一致风格的代码、测试、审查、审计并通过实际发布流程交付。 **大多数人难以成功设置 AI 项目——尤其是在的 AI 知识的情况下。** 这个工具旨在解决这个问题：回答几个问题，获得一个经过验证、有偏见的设置。 - **基于令牌和供应商中立** - 您的 Anthropic API 密钥 *或* Claude Code OAuth 令牌；仅限令牌，不使用 OAuth。没有第三方中心。 - **本地优先选项** - 在 **Ollama** 模型上运行简单工作（无需密钥），保留顶级模型用于复杂推理。 - **项目范围** - 机密和设置存储在项目（`.env`，`.aiflow/config.json`）中，而不是全局存储。 - **跨平台** - Windows、Linux、macOS。 > 🇩🇪 本文也提供 **[德语版本 → README.de.md](README.de.md)**。 **版本 0.1.1 · MIT 许可证 · [更新日志](CHANGELOG.md) · 📖 [文档站点](https://cyber93de.github.io/aiflow/)** --- ## 目录 1. [为什么选择 aiflow — 优势](#1-why-aiflow--the-advantages) 2. [功能概述](#2-feature-overview) 3. [安装](#3-install) 4. [构建第一个项目（逐步指南）](#4-build-a-first-project-walk-through) 5. [aiflow 安装的工具](#5-the-tools-aiflow-installs) 6. [内存：为什么使用图和 RAG 索引](#6-memory-why-a-graph-and-a-rag-index) 7. [代理 - 完整阵容](#7-agents--the-full-roster) 8. [斜杠命令技能](#8-slash-command-skills) 9. [交付工作流和分支模型](#9-delivery-workflow--branching-models) 10. [团队多个成员）](#10-team-collaboration-multiple-members. [配置远程主机（GitHub / GitLab / 自定义）](#11-configuring-the-remote-host) 12. [Claude 访问、Ollama 和添加更多12-claude-access-ollama--adding-more-models) 13. [使用 context7](#13-working-with-context7) 14. [添加您自己的 MCP 服务器](#14-adding-your-own-mcp-servers) 15. [您应该调整的配置（CLAUDE.md、团队偏好等）](#15-configuration-you-should-tune) 16. [命令参考](#16-command-reference) 17. [令牌优化](#17-token--cost-optimisation) 18. [CI/CD 和构建发布](#18-cicd-releases) 19. [项目布局](#19-project-layout) 20. [常见问题](#20-faq) 21. [故障排除](#21-troubleshooting) 22. [和感谢](#22-credits--thanks) 23. [反馈、想法和错误报告](#23-feedback-ideas--bug-reports) 24. [贡献](#24-contributing) [许可证](#25-license) 📖 **完整文档站点：** [cyber93de.github.io/aiflow](https://cyber93de.github.io/aiflow/) — 包括 **[AI 基础知识](https://cyber93de.github.io/aiflow/ai-basics)** （Claude Code、代理、内存、上下文窗口、技能、钩子 - 用通俗语言解释）和完整的 **[示例项目演练](https://cyber93de.github.io/aiflow/example-project)** （每个问题、每个默认值、第一个功能端到端）。 --- ## 1. 为什么选择 aiflow — 优势 - **强大的基础配置胜过没有配置。** 大多数 AI 编码项目从空白的 Claude 开始，重新发明规则、内存和工作流程，或者根本不做这些。aiflow 的目标是提供一个非常好的、通用的基础配置，可以在任何地方开箱即用，与从空白开始相比，可以节省大约 **70-80% 的配置。代理和为 **通用 根据您的项目进行参见第 7第 15 节不自定义，也优 Claude。 - **绪的代码才是最终目标。** aiflow 的代理生成的代码旨在交付：可重用、可靠、安全、基于当前标准；它们了解并尊重您的架构，合理地扩展它，批判性地审视的要求，并根据需要提出新的层次（缓存、服务缝隙）。按需报告 **可访问性（WCAG）**、**现代化潜力** 和 **安全问题**。 - **诚实对待令牌。省令牌是一个目标 - 原始人、rtkAG 检索都攻击它 - 但由于规则（测试、审查、关口），只能 **** 每个任务。另一方面，当需求在 **第一次** 传递中实现生产就绪时，您不需要重新提示、重新解释和重新细化 - 而 ** 才是节省令牌 **和时间** 的最终- **更好的内存，更少的幻觉。** 两个互补的代码索引加上持久的任务内存意味着查找** 而不是猜测或重新阅读数十个文件。参见第 6 节。 - **大幅减少令牌。** 原始人（简洁输出 ~ 较少输出令牌）、rtk（CLI 60-90% 较少）、图AG 检索（比读取整个文件少 ~）和可选的廉价/本地模型路由。通过iflow cost` 测量。 - **团队。** 问题共享的 Dolt 数据库中，该数据库通过您的 git同步。原子认两个人抢占同一任务；拉取-推送防止覆盖。参见第 10 节。 - **受可审计。**提交、强制谷歌验收标准审查关/质量/依赖/性能/文档审计、实际的分支 + 发布模型。 - **自主工作 Ralph 循环在无人值守的情况下完成任务、容器化或并在 `COMPLEBLOCKED` 处停止。 - **属于属于中心。** 所有内容都在您的密钥/令牌和您的基础设施上运行；机密永远不会离开项目。 --- ## 2. 功能概述 | 领域 | 您获得的内容 | |------|--------------| | **任务跟踪** | Beads（`bd`）- 具有依赖关系、状态、历史记录的 D的问题；上下文仍然存在 | |内存** |ify**（）+ **-code**（语义 RAG）claude/memory/` | | **外部 | **context7** MCP - 实时、版本正确的库文档 | |控制** | 在选择 **git**、**svn** 或 **none| **远程 | GitHub、Git、GitLab GitLab、BitForgejo、G自定义 URL - **牌** | | **主机 MCP** | git 主机 MCP 自动按远程类型| **模型** |API 密钥* OAuth）+ 可Ollama地模型，可选择安装 | | **** | claude 将简单/后台到廉价/ | | **代理** | 5 个交付 个审计/ 1 个棕代理 | |性** | Ralph 循环（交互式//容器化/ | | **质量 谷歌传统提交、格式/检查/测试 git 、架构 + 口审查、静态分析、目标度0 个新代码/重复项、0> 覆盖率 + E2E 关级日志记录、REST 端点的 `.http`DB 规则 §（3NF +用于新模式，棕地模式谨慎处理）分支**/gitflow/无-only、自动发布Ver/CalVer **团队** |问题数据库、原子、会话启动自动拉拉取前共享偏好 | 令牌节省**开启 caveman + rtk、图/RAG成本路由 | --- ## 3. 安装 **先决条件 [Node.js](nodejs.org)（）。aiflow安装其他所有内容。 ### Windows（PowerShell） ```powershell git clone https://github.com/Cyber93de/aiflow.git cd aiflow ./install.ps1 # 创建 aiflow shim + 将 bin 添加到用户 PATH aiflow doctor #窗口中立即生效终端：打开窗口 ``` ="center"><img src="docs/assets/terminal.gif"在 Windows 上安装 aiflow：克隆、1、low doctor" width"></p> ### Linux（```bash git clone https://githubyber93delow.git cd aiflow bash # 将 'a' 链接 PATH（~/. 或 /usr/localaiflow doctor ``` ### macOS） ```bash gitgithub.com/Cyber93de/a.git cd a bash install.sh # 与 Linux 相同；通过 Homebrew 安装可选aiflow doctor<p align="img src="docsterminal/install.gif="在 Linux/mac安装 aiflow隆、install.shiflow doctor" width="880"></p每个操作系统上，都会 **一次性询问安装 **git**Subversion（svn **Ollama 以便后续的iflow init` 只需询问您 Ollama 模型 ```bashiflow install-deps # 安装工具链（可选；提供） ，从 **[github.comber93de/aiflow/releases](https://github.com/Cyber93iflow/releases)** 获取打包的构建。 4. 构建第一个项目（逐步指南）bash -app && cd my-appiflow init 交互式问答 → 编写 .low/config.json →所有内容 aiflow init --no-token # 相同 caveman + rtk（完整、未过滤的输出） ``` <p align="img src="/terminal/init alt="aif：交互式问 令牌保存、内存、Claude、git/svn主机、Ollama 模型选择、分支模型" width="880"></p> `aiflow init` 询问（Enter = 默认值；令牌保存 + 强化图内存 **开启**）： 1. **caveman / rtk** - 令牌节省输出 + CLI 过滤（默认开启）。 2. **graph（结构图cocoindex（语义 R- 代码内存（）。 3. ****、****、**context7 MCP**（默认开启）。 4. **内存** - 启用持久内存学习和 **强度**（默认 `aggressive`）。 5. **Claude 访问** - `apikey`（ANTHROPIC_API_KEY）oauth`（` setup-token`. **版本控制** - `git` /` / `。 7. **远程 - `github-enterprise | | gitlab-selfbucket | forgejoitea | custom`，以及要连接的主机 MCP。基于。 8.规则** - 推送 + D步每个 Beads；会话启动时取。 9Ollama**？哪些模型？ `qwenoder`）。 10共享团队偏好 代码风格等. **项目目标/操作系统/IDE** 和 **git 分**（如果 VCS）。 > **过项目目标 - 它是最便宜的质量杠** 目标 以适应您的项目代理在规划或都会读取它 `init` 告诉 aiflow（问题 11）后通过 `a change-settings`手动写入到 **aude/memory/project.md`** 和 **`CLA §1`**好的目标是-4 个普通**做什么**、谁**、**** 和 ****。 示例：内部商店的 REST API。形架构在 Postgre。 正确性和胜过原始每个端点都测试的发货然后填充机密： ```bash 编辑 .env → 您的 git 主机令牌 + （ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN） aiflow shell # 加载 .env，启动带有所有 MCP 的 Claude Code ``` 在会话内： ```text /beready #准备好工作 create "添加点" -t --claim # 创建 + 认领implement 者构建它（代码 + 测试，谷歌/review-ac 审查者将其标准对照 ``` 代码库（棕地** `low init` 检测到它并提供iflow onboard它将代码学习到 `.claude/memory/`CLAUDE.md arc42 文档中启动时有相关信息 - 并 **建议项目目标**，基于它理解。 该被静默采用：加载程序 **要求您纠正它无头运行将其标记为 `PRO - 请确认` 在 `project-aim 中）。 随后aiflow-check` 获取架构转换为珠宝报告： <p"><img/assets/terminal/onboard.gif" alt="棕地入职：aiflow init 检测现有代码，加载程序学习它并建议项目目标供确认，然后 aiflow modernize-check" width="880"></p> 使用 **`aiflow index`**（图 + RAG）随时构建代码索引。 --- ## 5. aiflow 安装的`aif-deps`您的配置启用的内容--all 完整集）。都在用户空间 永远不会自动**核心（** Claude Code · Beads（`bd· Dolt（ 的数据库后端） · 远程的 git 主机 CLI（`gh`/`glab`）。 （启用时）：** claude-task claude-code rtk · ****（需要`）· **index-code**ccc`，需要`）·llama**选择的模型）。 容器运行（`docker/run.sh`）和 GitHub MCP 与 **Podman 或 Docker** 配合使用 - 请自行安装（从不自动安装）。 `aiflow doctor` 显示存在的内容，以及项目摘要（远程 + 主、VCS、Ollama 模型、内存：图/rag/context7 +）。 --- 6. 内存：为什么使用 RAG LLM 在会话之间会忘记并在重新读取文件时消耗令牌。aiflow 为 **分层上下文堆栈**便将问题路由到最便宜源。完整的路由表写入 **aude/memory/memory-policy.md`**： | 需要 | 来源 | 为什么 | |------|| | 当前任务、依赖、会话状态 | **Beads** (`bd`) | 结构化工作内存，在压缩后仍然存在 | | 持久项目事实/陷阱/环境怪癖 | **内存文件** (`.claude/memory/`) | 代码/中没有的散文 | | 符号定义位置、调用者、依赖方向 | **graphify** (MCP) | 精确的结构图 - 无需重新扫描 | | "查找概念 X 的代码"/语义/模糊 | **cocoindex-code** (`ccc` / MCP) | AST 感知 RAG，，~70% 更少令| 外部库/框架 API 文档 | **context7** (MCP) | 实时上游文档，避免 | | 仍然无法解决的问题 | 读取文件（s）| 仅在图 + RAG 将目标缩小后为什么使用图？** 代码是图（导入、调用、类型）。准确、廉价地回答 **结构** 问题（“谁调用 `parseToken`？什么依赖于 `auth`- 无需猜测，无需重新读取，并且它可以阻止重复代码，因为代理可以 **看到** 现有代码为什么还使用 RAG？** 图无法回答 **模糊** 问题（“哪里处理重试逻辑？”）。cocoindex-code 将代码 AST 意识地分块 **本地** （句子转换器，无需 API 密钥），并通过 - 比打开文件使用的令牌70%。它是增量式的：只有更改的文件会重新嵌入。 随时使用 **`aiflow index`**（图cc 索引）刷新 ** 索引（增量）。 7. 代理完整阵容 专业子代理位于 `.claude/agents/`。Claude `description` 选择一个，或者您可以调用它。提供的代理是通用** - 一个强大、通，而不是终点：**根据您的自定义它们**，通过编辑它们的 Markdown（提示、允许的 `toolsmodel:`）- 例如，您的领域语言、审查重点、测试堆### 交付代理（完成工作 代理 | 角色 | || | **architect** | - 生成 ADR、arc42 更新和任务分解。无功能代码。 | | **planner** | 将目标/史诗/问题转化为小的 Beads，并具有可测试的验收标准和实际依赖关系。 | | **** | 单个就绪珠的资深工程师 - 代码前分析（架构适合度、努力程度、复杂性），按需重构，SOLID/DRY/KISS/YAGNI，可测试的设计（DI，确定性），成熟的框架/模式优于自建，PO 级问题和有记录的决策，质量关口（静态分析，> 80% 覆盖率，BDD E，日志记录，`.http` 文件，指标目标）。 | reviewer** | 架构和** 质量关口 - 架构/设计/风险审查（模块边界、SOLID、技术债务、不足设计、漏洞、并发性、破坏性更改）+ 3a 清单；坚持 PASS / CHANGES REQUIRED。 | |** | 测试/QA 工程师面/边缘/边界/异常输入测试 + 测试质量审计（断言、确定性、独立当预分析标记高风险/时运行；报告错误而不是测试。 | ### 审计代理（手动，只读代码，文件优先珠子） | 代理 | 命令 | 文件问题标签 | | --- | --- | --- | | **安全顾问** | `aiflow security-check` | `[security-advisor]` | | **质量检查** | `aiflow quality-check` | `[technical issue]` | | **依赖审计器** | `aiflow dependency-check` | `[dependency]` | | **测试间隙顾问** | `aiflow test-gap` | `[test gap]` | | **性能顾问** | `aiflow perf-check` | `[performance]` | | **文档同步** | `aiflow docs-check` | `[docs]` | | **无障碍检查器** | `aiflow a11y-check` | `[accessibility]` — 严格的WCAG 2.2 AA审计所有UI表面；还建议为E2E套件（axe-core/Pa11y/Lighthouse CI）使用自动化的无障碍工具。不属于交付循环。 | | **需求检查** | `aiflow requirements-check` | *仅报告* （建议；评估问题质量与架构；不更改） | | **现代化顾问** | `aiflow modernize-check` | *仅报告* —遍历整个棕色场代码库，并提出现代化概念（微服务优于单体，REST/云原生优于SOAP/旧MQ，git优于svn，支持的堆栈，缺少单元/BDD/E2E测试框架）到 `.aiflow/modernization-report.md` ；架构师审查并可选地将它们输入珠子。不属于交付循环。 | ### 棕色场代理 | 代理 | 角色 | | --- | --- | | **上线引导** | 研究现有的代码库，并将学习内容持久化到 `.claude/memory/` 、 `CLAUDE.md` 和 arc42 — 未来会话开始时有据可查；提出项目目标并要求您确认它。仅写入 `docs/memory` 。 | **每个交付代理的共同点：** 仅生产就绪输出（谨慎使用低成熟度技术 — 审查者和测试者标记它），小类 / KISS（分割与征服 + 接口而不是巨型类），默认情况下是最先进的（不像SOAP或XML-over-REST这样的旧选择，从不默默构建），避免单体和刻意的 数据/性能选择（Redis/SQLite/Elasticsearch在它们有回报时被考虑）。每个代理的完整详细信息： [文档 → 代理](https://cyber93de.github.io/aiflow/agents)。 --- ## 8. 斜杠命令技能 在克劳德代码中可触发（ `.claude/commands/` ）： - **交付：** `/intake-issue <n>` （拉取GitHub/GitLab/Bitbucket问题 → 珠子）， `/decompose <goal|prd>` （任务主人 → 珠子）， `/plan-epic` ， `/implement [bead] [ralph|no-ralph]` （预分析首先；未指定 → 实现者自动决定 — 或尊重写入问题本身的“使用拉尔夫循环”注释）， `/review-ac` ， `/arch "<question>"` 。 - **审计：** `/security-check` ， `/quality-check` ， `/requirements-check` ， `/dependency-check` ， `/test-gap` ， `/perf-check` ， `/docs-check` ， `/a11y-check` （严格的WCAG）， `/modernize-check` （棕色场现代化报告）。 - **棕色场/定位：** `/onboard` ， `/explain <path>` ， `/standup` 。 珠子和拉尔夫循环也作为插件技能提供（ `/beads:ready` ， `/beads:decision` ， `/ralph-loop` ）。 --- ## 9. 交付工作流程和分支模型 ``` 问题（GitHub / GitLab / Bitbucket / ...） └─ /intake-issue ─▶ 珠子任务（带有验收标准） └─ /decompose（任务主人） ─▶ 子任务 + 依赖关系 └─ bd ready --claim ─▶ 选择并认领任务 └─ /implement ─▶ 代码 + 测试，谷歌风格 （实现者） └─ /review-ac ─▶ 与验收标准对比（审查者） └─ 提交（符合约定的提交 + 珠子ID） ─▶ PR ─▶ 发布 └─ aiflow close-sync ─▶ 推送 + Dolt-sync 问题 ``` 一个功能端到端 — 任务，预分析，产品负责人问题与记录的决策，版本化和 安全的API，测试 + `.http` 文件，审查门，关闭： <p align="center"><img src="docs/assets/terminal/workflow.gif" alt="aiflow delivery workflow: bd create, /implement with pre-analysis and PO question, /review-ac PASS, bd close" width="880"></p> **分支模型** （ `aiflow init` / `change-settings` ，仅当VCS = git）。aiflow写入 `.aiflow/branching.json` + 可读的 `docs/branching.md` ，创建永久分支，播种 `VERSION` ，并安装强制执行： - **模型** — `simple` （主 + 开发） · `gitflow` （ `feature/*` 来自开发， `hotfix/*` 来自主） · `none` 。 - **严格规则** — 强制分支源/目标和命名。 - **仅PR** — 不直接推送到主/开发；仅通过验证的PR合并。 - **自动发布** — 合并开发 → 主会创建一个发布。 - **版本策略** — SemVer或CalVer；可选的发布标签。 - **chore/\*** — 独立于功能/热修复规则的chore分支。 强制执行： `pre-push` 钩子阻止直接推送到受保护的分支； `aiflow protect` 在GitHub上应用真正的服务器端分支保护； `aiflow release [--push]` 提升版本，标签和提升开发。 --- ## 10. 团队协作（多个成员） 珠子问题生活在**共享的Dolt数据库**中，通过 `refs/dolt/data` 在您的git远程同步 — 整个团队的单个问题图谱，无需额外的服务器。 - **在会话开始时同步。** `SessionStart` 钩子自动运行 `bd dolt pull` （安全，尽力而为，从不推送；通过 `sync.pullOnStart` 退出）。或手动： `aiflow sync` 。 - **原子认领。** `bd ready --claim` / `bd update <id> --claim` 将指派者 = 您 + 状态 = 进行中设置为一步，因此 **两个人永远不会获得相同的任务** 。 `bd ready --unassigned` 显示空闲工作。 - **始终先拉取然后再推送。** `aiflow sync` 和 `aiflow close-sync` 先拉取，因此您合并团队成员的问题更改而不是覆盖它们。在冲突时： `bd dolt pull` （合并），解决，推送。从不强制推送。 - **状态是协调信号。** 保持它最新；过时的状态 = 重复工作。 - **发现的工作 → 一个新的珠子** （ `--deps discovered-from:<id>` ）； **决策 → `/beads:decision`** （有理由记录）所以整个团队看到 *为什么* 。 - **共享偏好** （代码样式，语言）生活在提交的 `.aiflow/team-prefs.json` 中 — 整个团队继承它们；个人调整保持本地。 --- ## 11. 配置远程主机 aiflow **仅基于令牌** — git主机 **没有OAuth** 。在init/change-settings时选择类型；匹配的CLI和MCP会自动连接。 | 远程类型 | 基本网址 | 令牌环境（ `.env` ） | 主机MCP连接 | | --- | --- | --- | --- | | `github` | github.com | `GITHUB_TOKEN` | github-mcp-server | | `github-enterprise` | 您的GHE网址 | `GITHUB_TOKEN` | github-mcp-server（设置 `GITHUB_HOST` ） | | `gitlab` / `gitlab-self` | gitlab.com / 您的网址 | `GITLAB_TOKEN` | server-gitlab（设置 `GITLAB_API_URL` ） | | `bitbucket` | 您的网址 | `BITBUCKET_TOKEN` | atlassian-bitbucket | | `forgejo` / `gitea` | 您的网址 | `GIT_REMOTE_TOKEN` | gitea-mcp-server（设置 `GITEA_URL` ） | | `custom` | 任意网址 | 您的环境变量 | 从列表中选择（或 `none` ） | **GitHub示例：** 创建一个具有repo + issues + pull_requests范围的PAT → 将其放入 `.env` 作为 `GITHUB_TOKEN` 。 **GitLab示例：** 创建一个具有 `api` 范围的个人访问令牌 → `GITLAB_TOKEN` 。对于自我管理的/企业版，请在init时提供基本网址；aiflow将API网址/主机连接到MCP。 珠子问题同步（ `bd github` / `bd gitlab` ）和Dolt同步使用相同的远程。以后可以通过 `aiflow change-settings` 更改任何内容（重新渲染 `.mcp.json` ，钩子等）。 --- ## 12. 克劳德访问，奥拉玛和添加更多模型 **克劳德访问** （ `.aiflow/config.json → claude.auth` ，两者都支持，OAuth优先，如果两者都设置）： - `apikey` → `ANTHROPIC_API_KEY` （按需付费， [console.anthropic.com](https://console.anthropic.com) ）。 - `oauth` → 运行 `claude setup-token` → `CLAUDE_CODE_OAUTH_TOKEN` （使用您的克劳德计划）。 **奥拉玛（本地，无API密钥）。** 在init时启用，或： ```bash aiflow ollama add qwen3-coder # 将模型添加到配置 + 拉取 aiflow ollama pull # 拉取配置中列出的所有模型 aiflow ollama list # 已安装的模型 ``` 选定的模型被写入 `.aiflow/router-config.json` 作为提供者，因此它们实际上用于简单/后台工作： ```bash aiflow shell --router # 将廉价/后台步骤路由到本地模型 ``` **添加更多/云模型** （DeepSeek，OpenRouter，Gemini，...）：将提供者 + 密钥添加到 `~/.claude-code-router/config.json` （从不提交）并在配置中启用 `router` 。 `.env` 还列出了可选密钥（ `DEEPSEEK_API_KEY` ， `OPENROUTER_API_KEY` ， `GEMINI_API_KEY` ）。将琐碎步骤路由到廉价模型，保持顶级克劳德模型用于硬推理；用 `aiflow cost` 衡量。 --- ## 13. 使用context7工作 **context7** 是一个MCP服务器，它为您的库获取 **实时，版本正确的文档** — 因此代理根据实际的当前API编码，而不是过时的记忆。默认情况下启用（ `mcp.context7` ）。 - 在会话中，只需正常询问（“使用最新的 `zod` 架构API”） — 代理调用context7拉取当前文档。您也可以提示它： *“检查context7获取当前的Prisma迁移API”* 。 - 它 **无密钥** ； `.env` 中的 `CONTEXT7_API_KEY` 提高速率限制。 - 将它与代码索引配对： **context7** = *外部* 库文档， **graphify/cocoindex** = *您的* 代码。 --- ## 14. 添加您自己的MCP服务器 aiflow从 `.aiflow/config.json` 生成 `.mcp.json` ，但您可以添加任何额外的MCP服务器 — 您对aiflow不管理的服务器的编辑将在重新渲染时保留。添加一个条目： ```jsonc { "mcpServers": { "my-server": { "command": "npx", "args": ["-y", "@scope/my-mcp-server"], "env": { "MY_TOKEN": "${MY_TOKEN}" } // 通过.env进行密钥管理，从不内联 } } } ``` 然后在 `.claude/settings.json` 中允许它在 `permissions.allow` 下（例如 `"mcp__my-server"` ）并将任何密钥放入 `.env` （gitignored）。对于社区验证的服务器，请浏览市场： `npx claude-code-templates@latest` 。提示：更喜欢专注的MCP而不是广泛的MCP — 工具越少 = 上下文越少，错误路径越少。 --- ## 15. 您应该调整的配置 所有内容都由 **`.aiflow/config.json`** 驱动（已提交，无密钥）。使用 `aiflow change-settings` 交互式编辑它（重新渲染 `.mcp.json` ，钩子，分支，内存） — 切换版本控制（git/svn），选择不同的Ollama模型，或完全关闭令牌保存，并使用 `--no-token-saving` ： <p align="center"><img src="docs/assets/terminal/settings.gif" alt="aiflow change-settings: switch vcs, pick Ollama models, disable token saving with --no-token-saving" width="880"></p> 最值得调整的文件： - **`CLAUDE.md`** — 每个代理阅读的操作规则（项目概述，架构提示，代码样式，任务工作流程，git规则，内存/上下文栈，通信）。填写 `[EDIT ME]` 块（§1概述，§2架构） — 这是最大的质量杠杆。 - **`.aiflow/team-prefs.json`** （“偏好”） — 共享的，版本化的团队/用户偏好：代码样式预设，语言，约定。已提交，以便团队继承它们；覆盖 `CLAUDE.md §3` 。 - **`.claude/memory/`** — `project-aim.md` （目标 + 架构）， `dev-environment.md` ， `memory-policy.md` （检索路由 + 学习强度）。保持这些最新。 - **`.claude/settings.json`** — 权限（允许/拒绝），钩子（caveman，格式化程序，珠子同步），MCP允许列表。 - **`.aiflow/branching.json` / `docs/branching.md`** — 分支 + 发布模型。 - **`.env`** — 所有令牌/密钥（gitignored，从不全局）。 `config.json` 形状： ```jsonc { "caveman": { "enabled": true, "mode": "full" }, "rtk": { "enabled": true }, "router": { "enabled": false }, "graphify": { "enabled": true }, "taskmaster": { "enabled": true }, "mcp": { "filesystem": true, "context7": true, "cocoindex": true }, "memory": { "enabled": true, "graph": true, "intensity": "aggressive" }, "claude": { "auth": "apikey" }, "vcs": { "system": "git" }, "remote": { "type": "github", "baseUrl": "https://github.com", "api": "github-api", "tokenEnv": "GITHUB_TOKEN", "mcp": "github" }, "sync": { "askOnClose": true, "pullOnStart": true }, "ollama": { "enabled": false, "url": "http://localhost:11434", "models": [] }, "teamPrefs":{ "enabled": false, "codeStyle": "google" }, "project": { "aim": "…", "architecture": "…" }, "dev": { "os": "windows", "ide": "vscode" }, "git": { "model": "gitflow", "strict": true, "prOnly": true, "autoRelease": true, "versionStrategy": "semver", "releaseTags": true, "chore": true } } ``` --- ## 16. 命令参考 ```text aiflow init [path] [--force] [--no-git] [--no-beads] [--yes] [--no-token-saving] 引导一个项目（--no-token-saving = caveman + rtk 关闭） aiflow install-deps [--all] 安装缺失的工具（启用配置；--all = 完整集） aiflow change-settings [--no-token-saving] 调整配置，然后重新渲染所有内容 aiflow shell [--router] 加载.env然后启动克劳德代码（--router = 廉价/本地模型） aiflow sync [pull|push|both] 团队同步：git + 珠子（dolt）拉取/推送 aiflow close-sync <id> 在问题关闭时：提示推送 + Dolt-同步远程 aiflow ollama [pull|add <m>|list] 管理本地Ollama模型 aiflow index 刷新代码内存：graphify（图）+ cocoindex（RAG） aiflow ralph "<prompt|bead id>" 运行无头拉尔夫循环 aiflow onboard 将现有代码库学习到内存 + CLAUDE.md + arc42 aiflow security-check | quality-check | requirements-check | dependency-check aiflow test-gap | perf-check | docs-check | a11y-check 按需审计 → 珠子问题 aiflow modernize-check 棕色场现代化概念 → 建筑师报告 aiflow release [--push] 按照分支模型切割发布 aiflow protect 应用服务器端分支保护（GitHub） aiflow cost [...] ccusage的令牌/成本基线 aiflow doctor 检查先决条件 + 项目摘要 aiflow upgrade 更新捆绑的工具链 aiflow version ``` --- ## 17. 令牌和成本优化 **首先设定期望值：** 令牌节省是一个真正目标，但aiflow的许多质量规则（测试，覆盖率门控，静态分析，架构审查）故意在正确性上下功夫。净收益来自 **不必问两次** ：一个在第一次传递就生产就绪的需求不需要重新提示和不需要返工 — 那样节省的令牌（和时间）比任何输出过滤器都要多。 杠杆： - **caveman** — 简洁的输出模式（~75%较少的输出令牌；代码/提交/安全保持正常）。默认开启。 - **rtk** — 在进入上下文之前过滤/压缩冗长命令输出（60-90%较少）。默认开启。 - **优先完整输出？** `aiflow init --no-token-saving` / `aiflow change-settings --no-token-saving` 在一个标志中切换caveman + rtk关闭。 - **图 + RAG检索** — 从graphify/cocoindex回答而不是读取整个文件（~70%较少）。 - **模型路由** — 通过 `aiflow shell --router` 将简单/后台步骤发送到廉价或本地（Ollama）模型。 - **先衡量** — `aiflow cost` （ccusage）显示真实支出，以便您优化重要的内容。 --- ## 18. CI/CD 和发布构建 - **`.github/workflows/ci.yml`** — 在推送/拉取请求时验证工具链：所有脚本上的 `bash -n` ，shellcheck（建议），模板的JSON验证，PowerShell解析，以及 **dry-run构建** 的每个操作系统存档（作为工件上传）。 - **`.github/workflows/release.yml`** — 在每次推送到 `main` 时，如果 `VERSION` 没有匹配的标签，它会构建每个操作系统的存档（ `linux.tar.gz` ， `macos.tar.gz` ， `windows.zip` + SHA256SUMS），标记 `v<VERSION>` ，并发布GitHub发布。 **增加 `VERSION` ，推送 → 创建发布。** 项目还获取 `.github/workflows/ci.yml` （检测Node/Python/Go/Dart → 格式 + 测试）和 `.github/workflows/agent.yml` （在手动调度， `agent` 问题标签或夜间运行Ralph循环；身份验证来自 `ANTHROPIC_API_KEY` **或** `CLAUDE_CODE_OAUTH_TOKEN` 存储库秘密）。 在本地构建与CI相同： ```bash ver=$(cat VERSION); stage="aiflow-$ver" mkdir -p "dist/$stage" && cp -r bin lib templates install.sh install.ps1 README*.md LICENSE VERSION "dist/$stage/" ( cd dist && tar -czf "aiflow-$ver-linux.tar.gz" "$stage" ) ``` --- ## 19. 项目布局 ``` your-project/ ├─ .aiflow/ │ ├─ config.json # 唯一的真相来源（已提交） │ ├─ team-prefs.json # 共享的团队偏好（已提交） │ ├─ router-config.json # 生成：Ollama/成本提供者（gitignored） │ ├─ bd-close-sync.sh # 关闭 → 提示推送 + Dolt-同步 │ └─ *.sh # 审计/发布/拉尔夫助手 ├─ .beads/ # 珠子问题数据库（Dolt） ├─ .claude/ │ ├─ agents/ 命令/ # 子代理 + 斜杠命令 │ ├─ hooks/ # caveman，格式化程序，珠子同步（SessionStart） │ ├─ memory/ # 项目目标，开发环境，内存策略 │ └─ settings.json # 权限 + 钩子 + MCP允许列表 ├─ .githooks/ # commit-msg，pre-commit，pre-push（强制执行） ├─ docs/architecture/ # arc42 + ADRs ├─ .mcp.json # 从配置生成（主机MCP，graphify，cocoindex，context7，...） ├─ CLAUDE.md # 每个代理阅读的操作规则 └─ .env # 密钥（gitignored，从不全局） ``` ## 20. 常见问题 **我需要 Anthropic API 密钥吗？** 您需要 API 密钥或 Claude Code OAuth令牌（`claude setup-token`）——请选择初始化时的 `claude.auth`。 **它是否支持离线/私有模式？** 代码索引（cocoindex-code）和嵌入是**本地的**（无需密钥）。使用Ollama，您也可以在本地运行模型。Claude本身仍会调用Anthropic。 **我的数据会被发送到哪里？** 密钥存储在 `.env` 中（gitignored，永不全局）。Claude请求所需的数据仅发送到 Anthropic（或通过路由器发送到您的本地模型）。 **graphify vs cocoindex — 我是否需要两者？** 它们是互补的：graphify准确回答**结构性**问题；cocoindex廉价回答**语义/模糊**问题。两者都推荐使用（§6）。 **如何添加另一个模型？** Ollama：`aiflow ollama add <model>`。云端：将其添加到 `~/.claude-code-router/config.json` 并启用 `router`（§12）。 **如何使用 GitLab / Bitbucket / 自托管代替 GitHub？** `aiflow change-settings` → 选择远程类型（或 `custom` + 基地址）→ 将令牌放入 `.env`（§11）。 **多人能否在一个项目中工作？** 是的 — 这是一个核心功能（§10）：共享 Dolt 问题数据库，原子声明，会话启动拉取，拉取前推送。 **我之后可以改变主意吗？** `aiflow change-settings` 重新运行问答并重新渲染 `.mcp.json`、钩子、分支和内存。 **我必须预安装工具吗？** 不。安装程序提供 git/svn/ollama；`aiflow install-deps`（或 `aiflow init`）安装其余部分。 **某些内容引用错误的 git 主机/令牌？** 重新运行 `aiflow change-settings`；检查 `.env` 是否有指定的令牌环境变量；`aiflow doctor` 显示已解析的配置。 ## 21. 故障排除 - **`jq is required`** — 安装 jq（`aiflow install-deps` 执行此操作）。aiflow 使用它读写 `config.json`。 - **`bd`/Dolt 错误** — `aiflow install-deps` 安装两者；`bd dolt status` 检查服务器。 - **MCP 服务器无法启动** — 运行 `aiflow doctor`；检查工具是否已安装（`ccc`、`graphify`、Docker 用于 GitHub MCP）以及 `.env` 中的令牌环境变量是否与 `remote.tokenEnv` 匹配。 - **Ollama 模型未使用** — 启用 `router` 并运行 `aiflow shell --router`；确认 `.aiflow/router-config.json` 列出您的模型并且 `ollama list` 具有它们。 - **Dolt 同步冲突** — `bd dolt pull`（合并），解决，然后 `bd dolt push`。永远不要强制推送。 - **报告错误** — 在 https://github.com/Cyber93de/aiflow/issues 上创建一个问题，并附上重现步骤。 ## 22. 鸣谢与感谢 aiflow 是胶水。感谢它所依赖的项目 — 请为它们加星并支持它们： - **[Claude Code](https://docs.claude.com/en/docs/claude-code)** （Anthropic）— 所有构建的基础代理运行时。 - **[Beads](https://github.com/steveyegge/beads)** — Dolt 支持的问题跟踪器；跨会话的持久任务内存。 - **[Dolt](https://github.com/dolthub/dolt)** （DoltHub）— 使团队问题同步工作的版本化 SQL 数据库。 - **[graphify](https://github.com/safishamsi/graphify)** — MCP 上的结构化代码知识图谱。 - **[CocoIndex](https://github.com/cocoindex-io/cocoindex)** & **[cocoindex-code](https://github.com/cocoindex-io/cocoindex-code)** — 增量、AST 感知的语义 RAG 索引（`ccc`）。 - **[Context7](https://github.com/upstash/context7)** （Upstash）— MCP 上的实时、版本正确的库文档。 - **[claude-task-master](https://github.com/eyaltoledano/claude-task-master)** — 目标/PRD → 任务树。 - **[claude-code-router](https://github.com/musistudio/claude-code-router)** — 适用于成本/本地模型的路由。 - **[Ollama](https://ollama.com)** — 本地模型运行时（无需 API 密钥）。 - **[rtk](https://www.rtk-ai.app/)** — CLI 输出过滤以减少上下文。 - **[ccusage](https://github.com/ryoppippi/ccusage)** — 令牌/成本分析。 - **[claude-code-templates](https://github.com/davila7/claude-code-templates)** — 社区代理/命令/MCP/钩子。 - **[Model Context Protocol](https://github.com/modelcontextprotocol/servers)** — MCP 服务器生态系统。 商标和项目归各自所有者所有；aiflow 是一个独立的集成，不隶属于或得到它们的认可。 ## 23. 反馈、想法和错误报告 **该项目依赖您的输入 — 而且非常欢迎。** 无论是粗略的想法、功能请求、“为什么这样工作？”还是直接的批评：尽管提出。诚实的反馈是 aiflow 变得更好的方式。 - 💡 **想法和建议** — 在 [GitHub Discussion](https://github.com/Cyber93de/aiflow/discussions) 或 [issue](https://github.com/Cyber93de/aiflow/issues) 上提出。没有想法太小或太大。 - 🗣️ **欢迎批评** — 告诉我们什么令人困惑、笨拙或缺失。分歧是有用的。 - 🐛 **错误报告** — 在 [issue](https://github.com/Cyber93de/aiflow/issues) 上提出重现步骤、您的操作系统和相关的 `aiflow doctor` 输出。小型重现 = 快速修复。 - 🙌 **支持** — 如果 aiflow 对您有帮助，存储库上的 ⭐、分享的链接或友善的话语真的会让人感到高兴。感谢您在这里。 这里**没有付费层级，也没有捐赠请求** — 最好的支持是您的反馈、星级和告诉朋友。 ## 24. 贡献 问题和PR欢迎在 **https://github.com/Cyber93de/aiflow** 上提出。aiflow 自己进行测试：它使用 Beads 进行自己的任务，遵守约定提交，并且 CI 工作流程（`bash -n`、shellcheck、JSON + PowerShell 验证）必须通过。请保持更改为项目范围且无秘密。 ## 25. 许可证 **MIT** — 版权 (c) 2026 Cyber93de。参见 [LICENSE](LICENSE)。 aiflow 不包含任何供应商 — 它安装/调用外部工具，每个工具都有其自己的许可证。参见 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) 以便确认。 _{**话题/关键词：** Claude Code · Anthropic Claude · AI 编码代理 · 代理软件交付 · MCP（模型上下文协议）· Beads · Dolt · graphify · 代码知识图谱 · CocoIndex · cocoindex-code · 语义代码搜索 · RAG · Context7 · Ollama · 本地 LLM · claude-code-router · rtk · caveman · 令牌优化 · Ralph 环 · gitflow · 约定提交 · GitHub · GitLab · Bitbucket · Forgejo · Gitea。&nbsp;·&nbsp; 建议的 GitHub 仓库话题：`claude-code`、`anthropic`、`ai-agent`、`mcp`、`beads`、`rag`、`code-search`、`ollama`、`context7`、`rtk`、`caveman`、`developer-tools`、`cli`。}