aidlc config 首次运行前必知的6件事（附常见陷阱）

aidlc config 首次运行前必知的6件事（附常见陷阱）

【免费下载链接】aidlc-workflowsAI-Driven Life Cycle (AI-DLC) adaptive workflow steering rules for AI coding agents项目地址: https://gitcode.com/GitHub_Trending/ai/aidlc-workflows

aidlc config是 AI-DLC 工作流框架里负责"把项目接入 AI 编码代理"的核心命令：一条命令即可在你的项目里生成 harness 配置树、工作区外壳和集成文件。很多新手第一次运行aidlc config就卡在权限、版本或 PATH 问题上。本文梳理aidlc config 首次运行前必知的 6 件事和 8 个常见陷阱，帮你一次跑通。

AI-DLC 是什么？它是一套 AI 驱动的软件生命周期（AI-DLC）自适应工作流规则，包含 5 个阶段、33 个环节、14 个代理和 11 种工作流档案，用于驾驭 Claude Code、Codex、Cursor 等 AI 编码代理。完整介绍见 README.md。

aidlc config 到底是什么？

先建立一个正确认知，避免后续踩坑：

• 它是本地命令、事务性执行：只在项目目录内创建/刷新文件，不联网、不创建工作流意图
• 它会生成：选定的 harness 目录树、aidlc/工作区外壳、根目录集成文件、投影戳和所有权基线
• 标准姿势是在打开 AI 代理之前运行它

官方推荐的三步流程（出自 docs/guide/18-install-and-lifecycle.md）：

cd your-project aidlc config --dry-run --json # 预览完整变更计划，不写任何字节 aidlc config # 正式执行 aidlc doctor # 健康检查

首次运行前必知的 6 件事

1️⃣ 先选对 harness，非交互模式必须显式指定

aidlc config --harness <name>决定把哪套 harness 的运行时树写进项目。可用的值有 7 个：

三个关键点：

• 不带--harness的裸aidlc config才会进入交互式向导（前提是终端可用）
• 脚本/CI 等非交互场景必须显式传--harness，否则会直接失败
• 项目已有配置戳（stamp）后，harness 就被固定了，刷新时不再允许更换

2️⃣ 项目目录必须"长得像项目"

aidlc config只会识别包含.git、package.json、Cargo.toml、go.mod或pyproject.toml的目录。在空目录里运行：

• 交互模式：会弹出确认提示
• 非交互模式：直接要求你传--project-dir <path>

💡 团队项目建议顺手把版本钉住，保证所有人用同一个引擎版本：

aidlc config --pin 2.5.45 git add .aidlc-version

3️⃣ 交互向导：先探测、后提问，最后一步才写文件

在人类终端里裸跑aidlc config，它会先做环境探测而不是直接提问：扫描 PATH 上的 harness CLI、项目状态、本地 AWS 凭据/区域、非交互式 hook 运行环境。

探测结果决定提问方式：

• 只探测到 1 个 harness → 直接给出三个选项：推荐默认/六步定制/ 退出（不写任何文件）
• 多个 harness → 先出编号选择器
• 零个 → 完整选择器

六步定制依次为：Harness、Model provider、Model effort preset、Plugins、MCP servers、settings layer。每步都有括号默认值，答错原地重问。所有文件只在最后的"确认答案表"按下 Enter 后才会写入。

4️⃣--yes不会替你点"同意 MCP"

这是新手最容易误解的一点：--yes和--json都不授予 MCP 服务器同意。

• MCP 只有两个值：defaults（加入随附的 MCP 条目）或none（不加入）
• 非交互模式且此前无选择记录时，默认落none
• 可靠的自动化脚本应显式传：--project-dir、--harness、--mcp defaults|none

aidlc config --project-dir "$PWD" --harness claude --mcp none --dry-run --json

5️⃣ 有进行中的工作流时，config 会被拒绝（且无法绕过）

刷新会改动项目的引擎和图谱文件，所以只要任何空间里有未完成的工作流（包括已暂停 parked 的工作流），aidlc config就会拒绝执行：

refusing to refresh while 2 workflow(s) are active

⚠️--force、--yes、--plan-token都绕不过这道守卫——它在计划阶段检查一次，在提交前的审计锁下再检查一次。解决办法只有一个：完成错误里列出的所有工作流，然后重跑。aidlc update/aidlc use只改机器状态、不动项目文件，所以随时可以执行。

6️⃣ 跑完 config ≠ 万事大吉：runtime、providers、trust 要逐一清零

config 成功后会做一次廉价的"安装结果扫描"，把遗留项打印出来。首次运行尤其要注意三件事：

① hook 的 PATH 问题（最经典的新手坑）

hook 跑在非交互式环境里，它用的 PATH 和你终端里的 PATH 不是一回事。典型症状：终端里bun好好的，hook 却全部不触发。用专门的诊断命令：

aidlc config runtime --show # 查看探测结果 aidlc config runtime --check # CI 反查，未通过则非零退出 aidlc config runtime --record-paths --yes # 把解析出的路径记入 harness.json

② 模型提供方（provider）的挂起动作

默认提供方是 Amazon Bedrock。凭据检测完全离线（只读环境变量的~/.aws/文件，绝不调用 STS）。有些验证离线做不了（比如 Bedrock 模型访问权限），会以"挂起动作"形式记录：

aidlc config providers --check # 有 pending 就非零退出 aidlc config providers --mark-done bedrock-model-access --yes

③ 信任（trust）

不同 harness 的信任机制不同，信任没配好之前 hook 是零触发：

• Codex：需要$CODEX_HOME/config.toml里完整的项目信任种子条目
• Kiro IDE：.vscode/settings.json的kiroAgent.trustedCommands需包含aidlc engine *

aidlc config trust --show aidlc config trust --check

常见陷阱速查表 🕳️

更多症状对照见 docs/guide/15-troubleshooting.md 的 Native Install 章节。

记忆点小结

1. config之前先--dry-run --json看计划，之后跑aidlc doctor收尾
2. 非交互模式三件套：--project-dir+--harness+--mcp defaults|none
3. 向导最后一步确认才写盘；--yes从不等于"同意 MCP"
4. 有活动工作流 → config 拒绝，这是设计如此
5. hook 不触发 → 先查aidlc config runtime，再查 trust，最后才怀疑框架
6. 团队项目用--pin+.aidlc-version锁定版本，告别"我的环境为什么不一样"

延伸阅读

• 安装与完整生命周期：docs/guide/18-install-and-lifecycle.md
• 从零到第一个工作流：docs/guide/01-getting-started.md
• 全部 CLI 命令参考：docs/guide/12-cli-commands.md
• 自定义与 settings 分层：docs/guide/13-customization.md
• config 实现源码：core/tools/aidlc-config-diagnostics.ts、core/tools/aidlc.ts

【免费下载链接】aidlc-workflowsAI-Driven Life Cycle (AI-DLC) adaptive workflow steering rules for AI coding agents项目地址: https://gitcode.com/GitHub_Trending/ai/aidlc-workflows