@elvis1513/auto-coding-skill 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,9 +23,24 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
23
23
 
24
24
  ## Release Notes
25
25
 
26
+ ### v2.0.3
27
+
28
+ - Fixed `doctor`, `light-gate`, `verify-target`, and Jenkins API verification to accept secret references via `*_password_env`.
29
+ - Kept direct `*_password` fields compatible for legacy projects while making the default template use environment-variable secret references.
30
+ - Updated docs so `docs/ENGINEERING.md` can stay Git-tracked without requiring committed secrets.
31
+
32
+ ### v2.0.2
33
+
34
+ - Added default Codex subagent templates under `.agents/agents`.
35
+ - `autocoding init --ai codex` and `autocoding init --ai all` now install the Codex agent templates automatically.
36
+ - Updated Codex agent defaults to current model names: `gpt-5.5`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`; highest reasoning uses `xhigh`.
37
+ - Added concrete capability routing for MCP servers, installed skills, plugins/apps/connectors, browser tools, GitHub, Figma, security review, and artifact workflows.
38
+ - Changed multi-agent guidance from unconditional delegation to a role model that works either as real subagents or as sequential main-agent phases.
39
+ - Hardened CLI help/argument validation, asset sync checks, and stricter autopipeline config diagnostics.
40
+
26
41
  ### v2.0.1
27
42
 
28
- - Updated the Codex installer target from `.codex/skills` to `.agents/skills`, matching current Codex global and project skill discovery.
43
+ - Updated the Codex installer target to `.agents/skills`, matching current Codex global and project skill discovery.
29
44
 
30
45
  ### v0.3.1
31
46
 
@@ -113,6 +128,8 @@ autocoding init --ai all
113
128
  # or: --ai codex / --ai claude
114
129
  ```
115
130
 
131
+ For Codex installs, the command also creates `.agents/agents/` with the default `explorer`, `fixer`, `reviewer`, `docs_researcher`, and `browser_debugger` subagents.
132
+
116
133
  2. Initialize docs and local scripts:
117
134
 
118
135
  ```bash
@@ -142,19 +159,19 @@ It must be committed to Git. Do not add it to `.gitignore`.
142
159
  - `target_env.name`
143
160
  - `target_env.frontend_base_url`
144
161
  - `target_env.frontend_username`
145
- - `target_env.frontend_password`
162
+ - `target_env.frontend_password` 或 `target_env.frontend_password_env`
146
163
  - `target_env.backend_base_url`
147
164
  - `target_env.backend_username`
148
- - `target_env.backend_password`
165
+ - `target_env.backend_password` 或 `target_env.backend_password_env`
149
166
  - `target_env.backend_root_username`
150
- - `target_env.backend_root_password`
167
+ - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
151
168
  - `target_env.health_base_url`
152
169
  - `target_env.health_path`
153
170
  - `jenkins.base_url`
154
171
  - `jenkins.ui_username`
155
- - `jenkins.ui_password`
172
+ - `jenkins.ui_password` 或 `jenkins.ui_password_env`
156
173
  - `jenkins.api_user`
157
- - `jenkins.api_password`
174
+ - `jenkins.api_password` 或 `jenkins.api_password_env`
158
175
  - `jenkins.trigger_branch`
159
176
  - `jenkins.image_repository`
160
177
  - `jenkins.image_tag_strategy`
@@ -172,14 +189,19 @@ It must be committed to Git. Do not add it to `.gitignore`.
172
189
 
173
190
  5. Tool selection rule during execution:
174
191
 
175
- - Prefer current MCP / skills / plugins / apps first.
176
- - Fall back to shell / manual work only when those capabilities are unavailable or insufficient.
192
+ - Local code, tests, git, and project gates: use shell, repo scripts, and `docs/tools/autopipeline/ap.py`.
193
+ - Current library/framework/API/CLI/cloud docs: use Context7 or the matching installed skill before coding against uncertain behavior.
194
+ - UI verification: use Browser/in-app browser for local pages, Chrome for the user's logged-in Chrome state, Playwright for deterministic automation, and Computer Use only for native or unsupported UI surfaces.
195
+ - GitHub/PR/CI: use GitHub connectors for remote PR, issue, review, and CI state; use local git for local diff, commit, and push.
196
+ - Figma/frontend/design, security review, data/reporting, and document artifacts: use the matching installed plugin or skill before manual recreation.
197
+ - Fall back to shell/manual work only when those capabilities are unavailable, insufficient, unreliable, or slower than direct execution.
177
198
 
178
199
  6. Collaboration rule during execution:
179
200
 
180
- - Prefer multi-agent mode.
181
- - Split research, design, implementation, verification, and documentation into parallel subtasks whenever the boundaries are clear.
182
- - Keep one main agent responsible for integration and final gates.
201
+ - Use `.agents/agents` as the default role model: `explorer`, `docs_researcher`, `browser_debugger`, `fixer`, `reviewer`.
202
+ - If the client permits subagents, split independent work across those roles.
203
+ - If the client cannot run subagents, execute the same role sequence in the main agent.
204
+ - Keep one main agent responsible for scope, integration, quality gates, docs closure, git state, and final delivery.
183
205
 
184
206
  ## AGENTS.md Constraint Example
185
207
 
@@ -193,17 +215,23 @@ It must be committed to Git. Do not add it to `.gitignore`.
193
215
  - If required docs are missing, create/update docs first, then code.
194
216
 
195
217
  ## Tooling Policy
196
- - Prefer currently available MCP servers, installed skills, plugins, and app connectors before shell/manual work.
218
+ - Route by source of truth:
219
+ 1) local code/tests/git -> shell + repo scripts
220
+ 2) current docs/API behavior -> Context7 or matching docs skill
221
+ 3) UI/browser proof -> Browser, Chrome, Playwright, or Computer Use by scenario
222
+ 4) PR/Issue/CI -> GitHub connector
223
+ 5) design/frontend/security/artifacts -> matching installed skill/plugin
197
224
  - When a connector or MCP can read or write the authoritative source directly, use it instead of retyping or duplicating state.
198
225
 
199
226
  ## Multi-Agent Policy
200
- - Default to multi-agent execution.
201
- - Before substantial work, split into parallel subtasks whenever boundaries are clear:
202
- 1) design / research
203
- 2) backend implementation
204
- 3) frontend implementation
205
- 4) validation / documentation / review
206
- - Keep one main agent responsible for task framing, integration, quality gates, and final delivery.
227
+ - Use `.agents/agents` roles:
228
+ 1) explorer
229
+ 2) docs_researcher
230
+ 3) browser_debugger
231
+ 4) fixer
232
+ 5) reviewer
233
+ - Spawn subagents only when the client supports and allows it; otherwise run the same role phases in the main agent.
234
+ - Keep one main agent responsible for task framing, integration, quality gates, docs closure, git state, and final delivery.
207
235
 
208
236
  ## Default Gate Policy
209
237
  - Default local gate is lightweight only.
@@ -218,10 +246,11 @@ It must be committed to Git. Do not add it to `.gitignore`.
218
246
  - Purpose: single source of project config + workflow rules.
219
247
  - How to record:
220
248
  - Fill YAML frontmatter once.
221
- - Keep target env front/backend usernames and passwords, Jenkins UI/API usernames and passwords, commands, docs paths here only.
249
+ - Keep target env front/backend usernames, Jenkins UI/API usernames, password fields or `*_password_env` references, commands, and docs paths here only.
222
250
  - Target environment also includes backend server root username/password.
223
- - This file is expected to be committed to Git and maintained in plaintext for this workflow.
251
+ - This file is expected to be committed to Git; prefer `*_password_env` for secrets so actual secret values stay in the current shell.
224
252
  - Remaining environment keys are all mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
253
+ - For secret fields, `doctor` requires either a direct `*_password` value or a `*_password_env` variable name. Commands that actually authenticate require the referenced environment variable to be set at execution time.
225
254
  - Do not duplicate config elsewhere.
226
255
 
227
256
  ### 2) docs/tasks/taskbook.md
@@ -0,0 +1,30 @@
1
+ name = "browser_debugger"
2
+ description = "浏览器调试代理,用于复现 UI 问题、收集控制台和网络证据。"
3
+ model = "gpt-5.5"
4
+ model_reasoning_effort = "xhigh"
5
+ sandbox_mode = "workspace-write"
6
+
7
+ developer_instructions = """
8
+ 你负责复现问题和采集证据,不优先修改业务代码。
9
+
10
+ 工作要求:
11
+ 1. 先复现,再下结论;无法复现时明确说明阻塞点。
12
+ 2. 按场景选择工具:
13
+ - localhost、file、应用内页面:优先 Browser / in-app browser;需要脚本控制时配合 node_repl。
14
+ - 需要复用用户 Chrome 登录态、扩展或已有标签页:使用 Chrome 控制能力;需要脚本控制时配合 node_repl。
15
+ - 需要稳定自动化复现、截图或 smoke test:使用 Playwright。
16
+ - 原生桌面 App 或没有专用连接器的 UI:才使用 Computer Use。
17
+ 3. 重点关注:
18
+ - 操作路径
19
+ - 实际表现
20
+ - 控制台报错
21
+ - 网络请求
22
+ - 状态变化
23
+ 4. 输出必须包含:
24
+ - 复现步骤
25
+ - 实际结果
26
+ - 预期结果
27
+ - 证据
28
+ - 根因候选
29
+ 5. 如果需要代码修复,只给出修复建议,交给 fixer 或主代理实施。
30
+ """
@@ -0,0 +1,21 @@
1
+ name = "docs_researcher"
2
+ description = "文档/API核对代理,负责确认框架、库、参数和版本行为。"
3
+ model = "gpt-5.4-mini"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你只负责核对文档和接口行为,不修改代码。
9
+
10
+ 工作要求:
11
+ 1. 涉及当前库、框架、SDK、CLI、云服务或 API 行为时,优先使用 Context7 等文档 MCP 或对应已安装 skill。
12
+ 2. 优先使用官方文档、项目仓库、发行说明或连接器返回的权威信息;不要用博客或二手资料替代官方来源。
13
+ 3. 重点核对:API签名、参数含义、版本兼容性、废弃项、默认行为、迁移要求。
14
+ 4. 输出要简洁、可引用、可落地。
15
+ 5. 优先返回:
16
+ - 结论
17
+ - 证据点
18
+ - 对当前项目的影响
19
+ - 建议给 explorer / fixer / reviewer 的下一步
20
+ 6. 如果文档不足以确认,明确标注“不确定”,不要猜。
21
+ """
@@ -0,0 +1,27 @@
1
+ name = "explorer"
2
+ description = "只读代码探索代理,用于定位调用链、关键文件和根因候选。"
3
+ model = "gpt-5.4-mini"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你只负责探索,不负责修改。
9
+
10
+ 工作要求:
11
+ 1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
12
+ 2. 先读项目已有文档、配置、路由、任务记录,再做结论。
13
+ 3. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
14
+ 4. 输出内容必须尽量具体到:
15
+ - 文件路径
16
+ - 函数名 / 方法名
17
+ - 关键结构体 / 类 / 接口
18
+ - 关键配置项
19
+ 5. 不要泛泛而谈,不要直接给大段修复方案。
20
+ 6. 输出格式:
21
+ - 问题入口
22
+ - 调用链
23
+ - 关键文件
24
+ - 根因候选
25
+ - 建议交给哪个代理继续处理
26
+ 7. 优先快速精准搜索,避免全仓库无差别扫描。
27
+ """
@@ -0,0 +1,25 @@
1
+ name = "fixer"
2
+ description = "实现型修复代理,适合小范围、快速、定点修改。"
3
+ model = "gpt-5.3-codex-spark"
4
+ model_reasoning_effort = "medium"
5
+ sandbox_mode = "workspace-write"
6
+
7
+ developer_instructions = """
8
+ 你负责小而准的实现修改。
9
+
10
+ 工作要求:
11
+ 1. 只在问题已经相对明确后再动手。
12
+ 2. 坚持“最小可辩护修改”原则。
13
+ 3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
14
+ 4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
15
+ 5. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
16
+ 6. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
17
+ 7. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
18
+ 8. 修改后运行聚焦门禁:优先项目 light gate,其次相关测试、typecheck、lint、git diff --check。
19
+ 9. 修改后输出:
20
+ - 修改文件
21
+ - 修改点
22
+ - 修改原因
23
+ - 验证方法
24
+ 10. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
25
+ """
@@ -0,0 +1,22 @@
1
+ name = "reviewer"
2
+ description = "代码审查代理,聚焦正确性、安全性、回归风险和测试缺失。"
3
+ model = "gpt-5.5"
4
+ model_reasoning_effort = "xhigh"
5
+ sandbox_mode = "read-only"
6
+
7
+ developer_instructions = """
8
+ 你是资深 reviewer,不负责写新功能,主要负责发现问题。
9
+
10
+ 工作要求:
11
+ 1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
12
+ 2. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
13
+ 3. 以 git diff、相关测试、接口契约、真实运行证据为基础,不凭风格偏好输出问题。
14
+ 4. 优先输出真实问题,不要输出样式洁癖式意见。
15
+ 5. 每条问题尽量包含:
16
+ - 问题点
17
+ - 影响范围
18
+ - 复现条件
19
+ - 建议修法
20
+ 6. 发现测试不足时,指出应补哪些测试或验证路径。
21
+ 7. 结论要按严重程度排序:高 / 中 / 低。
22
+ """
@@ -7,11 +7,11 @@ description: Use for a Claude/Codex engineering workflow with dev and verify mod
7
7
 
8
8
  This skill is for Go backend + frontend monorepo projects that rely on Jenkins to build and deploy after push. It supports both Claude and Codex. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when Jenkins and the real target environment must be completed before closure.
9
9
 
10
- `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Unused environment keys should be removed from the template instead of being left as placeholders.
10
+ `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
11
11
 
12
- Prefer already available MCP servers, installed skills, plugins, and app connectors over ad-hoc manual work whenever they can complete the task reliably.
12
+ At task start, inventory the current client capabilities before choosing a route: installed MCP servers, local skills, plugins/apps/connectors, browser/control tools, and repo scripts. Prefer those capabilities when they provide current, authoritative, or directly inspectable state.
13
13
 
14
- Default to multi-agent execution when the client supports it. Break work into independent design, research, implementation, validation, and documentation subtasks so Claude/Codex can run them in parallel whenever that reduces cycle time without weakening control of the main task.
14
+ Use multi-agent roles deliberately. When the client exposes subagent tools and the active runtime policy permits delegation, split independent research, exploration, implementation, browser verification, and review work. When delegation is unavailable or restricted, execute the same role sequence in the main agent instead of pretending parallelism is possible.
15
15
 
16
16
  ## Supported clients
17
17
 
@@ -20,22 +20,30 @@ Default to multi-agent execution when the client supports it. Break work into in
20
20
 
21
21
  ## Tooling policy
22
22
 
23
- Use available platform capabilities first:
23
+ Use the most direct authoritative capability for each task:
24
24
 
25
- 1) Prefer installed MCP servers for design context, documentation lookup, browser automation, issue/docs systems, and deployment/runtime inspection.
26
- 2) Prefer already installed local skills when the task matches them.
27
- 3) Prefer supported plugins/apps/connectors when they provide authoritative project context or can write back records.
28
- 4) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
25
+ 1) Local repo work: use shell, repo scripts, and `docs/tools/autopipeline/ap.py` for edits, tests, gates, git, and project-local verification.
26
+ 2) Current library/framework/API/CLI/cloud behavior: use a documentation MCP such as Context7 or the matching installed skill before coding migrations, config changes, or API integrations.
27
+ 3) Browser and UI verification: use Browser/in-app browser for localhost and app-owned sessions; use Chrome when the user's existing logged-in Chrome state is required; use Playwright for deterministic browser automation or terminal-first smoke tests; use Computer Use only for native apps or UI surfaces without a purpose-built connector.
28
+ 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend skills when the task depends on design context, visual implementation, screenshots, or generated UI.
29
+ 5) GitHub/PR/CI state: use GitHub connectors for PRs, issues, review comments, and Actions/CI metadata; use local git for local diff, staging, commits, and pushes.
30
+ 6) Security-sensitive changes: use reviewer/security skills or security scan capabilities for auth, permission, payment, file transfer, deployment, dependency, and data-boundary changes.
31
+ 7) Analytical or document artifacts: use Data Analytics, documents, PDFs, spreadsheets, presentations, or LaTeX skills/plugins for those artifact types, including render/validation steps.
32
+ 8) OpenAI/API keys and other secrets: use secure platform/key setup capabilities when available; do not paste, invent, or persist secrets outside the configured secure flow.
33
+ 9) Screen/recent-work context: use Chronicle or screenshot skills when the user references visible UI state or recent manual actions.
34
+ 10) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
29
35
 
30
36
  ## Collaboration policy
31
37
 
32
- Prefer multi-agent mode across the workflow:
38
+ Use `.agents/agents` role templates as the default collaboration model for Codex installs:
33
39
 
34
- 1) Split independent subtasks early when they can run in parallel.
35
- 2) Keep the main agent on the critical path: task framing, design decisions, integration, Jenkins / target-env verification, and final closure.
36
- 3) Use side agents for bounded work such as research, code slices, documentation updates, targeted regression checks, or review passes.
37
- 4) Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
38
- 5) A practical default split for Go fullstack work is: design/research, backend implementation, frontend implementation, validation/documentation.
40
+ 1) `explorer`: read-only repo discovery, call-chain tracing, config mapping, and root-cause candidates.
41
+ 2) `docs_researcher`: current external documentation, API signatures, version behavior, and compatibility checks.
42
+ 3) `browser_debugger`: browser reproduction, console/network evidence, screenshots, and UI behavior verification.
43
+ 4) `fixer`: bounded implementation after the cause and acceptance path are clear.
44
+ 5) `reviewer`: read-only correctness, security, regression-risk, and missing-test review.
45
+
46
+ The main agent always owns task framing, design decisions, integration, Jenkins / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
39
47
 
40
48
  ## Entry
41
49
 
@@ -46,6 +54,8 @@ autocoding init --ai codex
46
54
  # or claude / all
47
55
  ```
48
56
 
57
+ For Codex targets, this also installs the default subagent templates into `.agents/agents/`.
58
+
49
59
  2) Initialize docs/tooling:
50
60
 
51
61
  ```bash
@@ -83,19 +93,19 @@ Minimum required config for the default flow:
83
93
  - `target_env.name`
84
94
  - `target_env.frontend_base_url`
85
95
  - `target_env.frontend_username`
86
- - `target_env.frontend_password`
96
+ - `target_env.frontend_password` or `target_env.frontend_password_env`
87
97
  - `target_env.backend_base_url`
88
98
  - `target_env.backend_username`
89
- - `target_env.backend_password`
99
+ - `target_env.backend_password` or `target_env.backend_password_env`
90
100
  - `target_env.backend_root_username`
91
- - `target_env.backend_root_password`
101
+ - `target_env.backend_root_password` or `target_env.backend_root_password_env`
92
102
  - `target_env.health_base_url`
93
103
  - `target_env.health_path`
94
104
  - `jenkins.base_url`
95
105
  - `jenkins.ui_username`
96
- - `jenkins.ui_password`
106
+ - `jenkins.ui_password` or `jenkins.ui_password_env`
97
107
  - `jenkins.api_user`
98
- - `jenkins.api_password`
108
+ - `jenkins.api_password` or `jenkins.api_password_env`
99
109
  - `jenkins.trigger_branch`
100
110
  - `jenkins.image_repository`
101
111
  - `jenkins.image_tag_strategy`
@@ -33,19 +33,19 @@ target_env:
33
33
  name: ""
34
34
  frontend_base_url: ""
35
35
  frontend_username: ""
36
- frontend_password: ""
36
+ frontend_password_env: ""
37
37
  backend_base_url: ""
38
38
  backend_username: ""
39
- backend_password: ""
39
+ backend_password_env: ""
40
40
  backend_root_username: ""
41
- backend_root_password: ""
41
+ backend_root_password_env: ""
42
42
  health_base_url: ""
43
43
  health_path: ""
44
44
 
45
45
  jenkins:
46
46
  base_url: ""
47
47
  ui_username: ""
48
- ui_password: ""
48
+ ui_password_env: ""
49
49
  job_url: ""
50
50
  trigger_branch: ""
51
51
  image_repository: ""
@@ -53,7 +53,7 @@ jenkins:
53
53
  deploy_env: ""
54
54
  deploy_timeout_sec: 1800
55
55
  api_user: ""
56
- api_password: ""
56
+ api_password_env: ""
57
57
 
58
58
  docs:
59
59
  taskbook: "docs/tasks/taskbook.md"
@@ -87,7 +87,7 @@ docs:
87
87
  - 每次任务闭环后,必须清理临时文件、临时目录、日志、截图、构建缓存等非必要产物;仅明确需要保留的本地诊断目录允许保留。
88
88
  - 所有手工填写信息,只维护在本文件 frontmatter 中,其他文档不得重复配置。
89
89
  - `docs/ENGINEERING.md` 必须提交到 Git 管理,不允许写入 `.gitignore`。
90
- - 本 workflow 明确允许在 `docs/ENGINEERING.md` 中明文维护平台账号、密码,并随 Git 一起版本化。
90
+ - 目标环境和 Jenkins 密码默认通过 `*_password_env` 指向当前 shell 中的环境变量;确需兼容旧项目时才使用明文 `*_password` 字段。
91
91
  - 未参与默认流程的环境项不要保留占位;模板中未保留的字段视为已清理,不再额外配置。
92
92
 
93
93
  ---
@@ -97,15 +97,15 @@ docs:
97
97
  先填写 `docs/ENGINEERING.md` frontmatter 中的所有空值。重点包括:
98
98
  - `workflow.mode`:`dev` 或 `verify`,默认推荐 `dev`
99
99
  - `commands.light_gate`:推荐配置一个项目级快速门禁命令,作为默认本地校验入口
100
- - `target_env.*`:目标环境前端 / 后端地址、用户名、密码,必须全部填写且真实可用
101
- - `jenkins.*`:Jenkins UI/API 用户名、密码、Job、分支、镜像、部署环境,必须全部填写且真实可用
100
+ - `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
101
+ - `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
102
102
 
103
103
  字段说明:
104
- - `target_env.backend_username` / `target_env.backend_password`:目标环境后台账号
105
- - `target_env.backend_root_username` / `target_env.backend_root_password`:目标环境后台服务器 root 账号
106
- - `target_env.frontend_username` / `target_env.frontend_password`:目标环境前端登录账号
107
- - `jenkins.ui_username` / `jenkins.ui_password`:Jenkins 页面登录账号
108
- - `jenkins.api_user` / `jenkins.api_password`:Jenkins API 用户名 / 密码
104
+ - `target_env.backend_username` + `target_env.backend_password_env` 或 `target_env.backend_password`:目标环境后台账号
105
+ - `target_env.backend_root_username` + `target_env.backend_root_password_env` 或 `target_env.backend_root_password`:目标环境后台服务器 root 账号
106
+ - `target_env.frontend_username` + `target_env.frontend_password_env` 或 `target_env.frontend_password`:目标环境前端登录账号
107
+ - `jenkins.ui_username` + `jenkins.ui_password_env` 或 `jenkins.ui_password`:Jenkins 页面登录账号
108
+ - `jenkins.api_user` + `jenkins.api_password_env` 或 `jenkins.api_password`:Jenkins API 用户名 / 密码
109
109
 
110
110
  默认必填:
111
111
  - `workflow.mode`
@@ -114,18 +114,19 @@ docs:
114
114
  - `target_env.name`
115
115
  - `target_env.frontend_base_url`
116
116
  - `target_env.frontend_username`
117
- - `target_env.frontend_password`
117
+ - `target_env.frontend_password` 或 `target_env.frontend_password_env`
118
118
  - `target_env.backend_base_url`
119
119
  - `target_env.backend_username`
120
- - `target_env.backend_password`
120
+ - `target_env.backend_password` 或 `target_env.backend_password_env`
121
121
  - `target_env.backend_root_username`
122
- - `target_env.backend_root_password`
122
+ - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
123
123
  - `target_env.health_base_url`
124
124
  - `target_env.health_path`
125
+ - `jenkins.base_url`
125
126
  - `jenkins.ui_username`
126
- - `jenkins.ui_password`
127
+ - `jenkins.ui_password` 或 `jenkins.ui_password_env`
127
128
  - `jenkins.api_user`
128
- - `jenkins.api_password`
129
+ - `jenkins.api_password` 或 `jenkins.api_password_env`
129
130
  - `jenkins.trigger_branch`
130
131
  - `jenkins.image_repository`
131
132
  - `jenkins.image_tag_strategy`
@@ -161,28 +162,75 @@ docs:
161
162
 
162
163
  ## 1.5 工具使用策略(Claude / Codex 专属)
163
164
 
164
- 优先使用当前环境已安装、已授权、已可访问的工具能力:
165
+ 任务开始时先做能力盘点:当前可用的 MCP servers、已安装 skills、plugins / apps / connectors、浏览器控制能力、repo 脚本。能直接读取权威状态、当前文档或真实 UI 的能力,优先于手写推测。
165
166
 
166
- 1) MCP servers
167
- 2) 已安装 skills
168
- 3) plugins / apps / connectors
169
- 4) shell / 手工实现
167
+ 默认路由:
170
168
 
171
- 规则:
172
- - 做设计、查资料、查文档、查 Jenkins、查页面、写回外部系统时,优先调用现成能力。
173
- - 工具不可用、权限不足、结果不可靠时,才回退到 shell 或手工流程。
169
+ 1) 本地代码 / 测试 / Git / 门禁
170
+ 优先使用 shell、项目脚本、`docs/tools/autopipeline/ap.py`。本地 diff、提交、推送以 Git 实际状态为准。
171
+
172
+ 2) 当前库 / 框架 / SDK / API / CLI / 云服务文档
173
+ 优先使用 Context7 等文档 MCP 或对应已安装 skill,先确认版本、参数、默认行为、废弃项,再改代码。
174
+
175
+ 3) 浏览器与 UI 验证
176
+ - localhost、file、应用内页面:优先 Browser / in-app browser;需要脚本控制时配合 node_repl。
177
+ - 必须复用用户 Chrome 登录态、扩展或已有标签页:使用 Chrome 控制能力;需要脚本控制时配合 node_repl。
178
+ - 需要稳定自动化复现、截图或 smoke test:使用 Playwright。
179
+ - 原生桌面 App 或没有专用连接器的 UI:才使用 Computer Use。
180
+
181
+ 4) GitHub / PR / Issue / CI
182
+ 远端 PR、Issue、review comments、Actions/CI 状态优先用 GitHub connector;本地 diff、commit、push 仍用本地 Git。
183
+
184
+ 5) Figma / 视觉设计 / 前端体验
185
+ 设计上下文先用 Figma;视觉强相关页面优先使用 frontend / build-web / product-design 类 skill,并用浏览器截图或真实页面验证收口。
186
+
187
+ 6) 安全敏感变更
188
+ 鉴权、权限、支付、文件上传下载、部署、依赖、数据边界变更,默认安排 reviewer 或安全扫描能力做只读复核。
189
+
190
+ 7) 报告与文件类产物
191
+ Dashboard / 数据报告使用 Data Analytics;Word/PDF/表格/PPT/LaTeX 使用对应文档类 skill 或插件,并做渲染/校验。
192
+
193
+ 8) OpenAI/API key/密钥类操作
194
+ 使用平台提供的安全 key 创建或写入流程;不要在普通文档、日志或提交中手写、复制、持久化密钥。
195
+
196
+ 9) 屏幕与近期操作上下文
197
+ 当任务依赖用户当前屏幕、浏览器登录状态或最近手工操作时,优先使用 Chronicle / screenshot 类能力获取真实上下文。
198
+
199
+ 回退规则:
200
+ - 工具不可用、权限不足、结果不可靠或比直接执行更慢时,才回退到 shell 或手工流程。
174
201
  - 不重复手写工具已经能直接读取或写回的权威数据。
202
+ - 外部信息必须优先来自官方文档、项目连接器或真实运行状态。
175
203
 
176
204
  ---
177
205
 
178
206
  ## 1.6 多 Agent 协作策略(Claude / Codex 专属)
179
207
 
180
- 整个流程尽可能使用多 agent 并行推进。
208
+ 默认使用 `.agents/agents` 中的角色模型来拆解任务;只有在当前客户端明确提供并允许子代理/多代理工具时,才实际并行派发。若运行时策略不允许子代理,则由主 agent 按同一角色顺序串行完成,不假装并行。
181
209
 
182
- 规则:
183
- - 主 agent 负责任务定义、方案裁决、代码集成、轻量门禁、Jenkins/目标环境闭环、最终交付。
184
- - 子 agent 优先拆为:设计/调研、后端实现、前端实现、验证/文档。
185
- - 任务边界不清或需要强一致裁决时,由主 agent 保持控制,不机械拆分。
210
+ 默认角色:
211
+
212
+ 1) `explorer`
213
+ 只读探索:定位入口、调用链、关键文件、配置项、根因候选。
214
+
215
+ 2) `docs_researcher`
216
+ 文档/API 核对:确认当前版本行为、参数、兼容性、废弃项和官方建议。
217
+
218
+ 3) `browser_debugger`
219
+ 浏览器验证:复现路径、控制台、网络请求、截图、实际/预期行为。
220
+
221
+ 4) `fixer`
222
+ 定点实现:在问题和验收路径清晰后做最小可辩护修改,并运行聚焦校验。
223
+
224
+ 5) `reviewer`
225
+ 只读复核:正确性、安全性、回归风险、边界条件和测试缺口。
226
+
227
+ 主 agent 始终负责:
228
+ - 任务定义、范围裁决、方案取舍
229
+ - 代码集成和冲突处理
230
+ - 轻量门禁、Jenkins/目标环境闭环
231
+ - 文档闭环、Git 状态、最终交付
232
+
233
+ 任务边界不清、需要强一致裁决或涉及架构取舍时,由主 agent 保持控制,不机械拆分。
186
234
 
187
235
  ---
188
236
 
@@ -217,16 +265,16 @@ docs:
217
265
 
218
266
  ### 2.3 任务步骤
219
267
 
220
- 1. 需求确认
268
+ 1. 需求确认
221
269
  明确任务范围、影响服务、是否涉及 API/数据库/部署/Jenkins/前端页面。
222
270
 
223
- 2. 最小设计记录
271
+ 2. 最小设计记录
224
272
  普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
225
273
 
226
- 3. 开发实现
274
+ 3. 开发实现
227
275
  只修改本次任务必要文件,不做无关重构。
228
276
 
229
- 4. 本地轻量校验
277
+ 4. 本地轻量校验
230
278
  默认只跑最少必要检查:
231
279
  - 优先执行 `commands.light_gate`
232
280
  - 若未配置,则执行 `quick_test` / `test` / `build` 中最先配置的一项
@@ -234,22 +282,22 @@ docs:
234
282
  - API 文档检查
235
283
  - Jenkins 配置检查
236
284
 
237
- 5. 提交推送
285
+ 5. 提交推送
238
286
  `dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证 Jenkins 和目标环境。
239
287
 
240
- 6. Jenkins 验证
288
+ 6. Jenkins 验证
241
289
  仅 `verify` 模式默认执行。查看 Jenkins 构建、镜像、部署结果;失败则根据 Jenkins 日志修复,再次提交推送。
242
290
 
243
- 7. 目标环境验证
291
+ 7. 目标环境验证
244
292
  仅 `verify` 模式默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
245
293
 
246
- 8. 回归与证据记录
294
+ 8. 回归与证据记录
247
295
  只有真实执行过 Jenkins / 目标环境验证,或显式要求本地运行验证时,才允许把 `regression-matrix.md` 标为 `PASS`。
248
296
 
249
- 9. 闭环记录
297
+ 9. 闭环记录
250
298
  每个任务必须留下轻量闭环记录。`dev` 模式用 `DEV-CLOSED`,`verify` 模式用 `PASS` / `FAIL` / `PARTIAL`。
251
299
 
252
- 10. 配置入库
300
+ 10. 配置入库
253
301
  `docs/ENGINEERING.md` 中保留下来的环境信息、前端/后端账号、Jenkins 账号与密码必须 100% 填写、正确填写,并提交 Git 作为项目权威配置持续维护。
254
302
 
255
303
  ---
@@ -1,5 +1,5 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
- Prefer already available MCP servers, installed skills, plugins, and app connectors during design, research, verification, and documentation workflows.
3
- Prefer multi-agent mode whenever the task can be split into independent parallel subtasks without weakening integration control.
2
+ Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
+ Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
4
  Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
5
5
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -1,5 +1,5 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
- Prefer already available MCP servers, installed skills, plugins, and app connectors during design, research, verification, and documentation workflows.
3
- Prefer multi-agent mode whenever the task can be split into independent parallel subtasks without weakening integration control.
2
+ Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
3
+ Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
4
4
  Default to the lightweight local gate first, then use Jenkins build verification and real target-environment verification as the primary completion gate.
5
5
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
@@ -8,6 +8,7 @@ import argparse
8
8
  import base64
9
9
  import datetime as _dt
10
10
  import json
11
+ import os
11
12
  import time
12
13
  import urllib.parse
13
14
  import urllib.error
@@ -60,23 +61,32 @@ def _run_configured_command(repo: Path, cfg: dict, name: str) -> bool:
60
61
 
61
62
  def _jenkins_basic_auth_headers(cfg: dict) -> dict:
62
63
  jenkins_cfg = (cfg.get("jenkins") or {})
63
- user_candidates = [
64
- jenkins_cfg.get("api_user"),
65
- jenkins_cfg.get("ui_username"),
64
+ credential_pairs = [
65
+ ("api_user", "api_password"),
66
+ ("ui_username", "ui_password"),
66
67
  ]
67
- secret_candidates = [
68
- jenkins_cfg.get("api_password"),
69
- jenkins_cfg.get("ui_password"),
70
- ]
71
- user = next((_text(v) for v in user_candidates if _is_explicit_fill(v)), "")
72
- secret = next((_text(v) for v in secret_candidates if _is_explicit_fill(v)), "")
73
- if not user or not secret:
74
- raise APError(
75
- "Missing Jenkins API credentials. Fill jenkins.api_user and jenkins.api_password in docs/ENGINEERING.md."
76
- )
77
- raw = f"{user}:{secret}".encode("utf-8")
78
- auth = base64.b64encode(raw).decode("ascii")
79
- return {"Authorization": f"Basic {auth}"}
68
+ errors: list[str] = []
69
+
70
+ for user_field, secret_field in credential_pairs:
71
+ user = _text(jenkins_cfg.get(user_field))
72
+ if not _is_explicit_fill(user):
73
+ continue
74
+ try:
75
+ secret = _resolve_secret("jenkins", jenkins_cfg, secret_field)
76
+ except APError as exc:
77
+ errors.append(str(exc))
78
+ continue
79
+ raw = f"{user}:{secret}".encode("utf-8")
80
+ auth = base64.b64encode(raw).decode("ascii")
81
+ return {"Authorization": f"Basic {auth}"}
82
+
83
+ detail = "\n- " + "\n- ".join(errors) if errors else ""
84
+ raise APError(
85
+ "Missing Jenkins API credentials. Configure jenkins.api_user with "
86
+ "jenkins.api_password or jenkins.api_password_env, or configure "
87
+ "jenkins.ui_username with jenkins.ui_password or jenkins.ui_password_env."
88
+ + detail
89
+ )
80
90
 
81
91
 
82
92
  def _http_error_body(exc: urllib.error.HTTPError) -> str:
@@ -193,12 +203,12 @@ def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: b
193
203
  except Exception as retry_exc:
194
204
  raise APError(f"Jenkins API request failed after crumb retry: {url}\n{retry_exc}") from retry_exc
195
205
  else:
196
- raise APError(
197
- f"Jenkins API request failed: {url}\n"
198
- f"HTTP 403\n{body or '(empty response body)'}\n"
199
- "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
206
+ raise APError(
207
+ f"Jenkins API request failed: {url}\n"
208
+ f"HTTP 403\n{body or '(empty response body)'}\n"
209
+ "Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
200
210
  "Fill jenkins.base_url in docs/ENGINEERING.md if needed."
201
- ) from exc
211
+ ) from exc
202
212
  else:
203
213
  raise APError(
204
214
  f"Jenkins API request failed: {url}\n"
@@ -556,7 +566,14 @@ def _text(value: object) -> str:
556
566
 
557
567
 
558
568
  def _is_placeholder(value: object) -> bool:
559
- return _text(value).upper() in _INVALID_PLACEHOLDERS
569
+ raw = _text(value)
570
+ upper = raw.upper()
571
+ return (
572
+ upper in _INVALID_PLACEHOLDERS
573
+ or (raw.startswith("<") and raw.endswith(">"))
574
+ or upper.startswith("REPLACE_")
575
+ or upper.startswith("YOUR_")
576
+ )
560
577
 
561
578
 
562
579
  def _is_explicit_fill(value: object) -> bool:
@@ -564,6 +581,8 @@ def _is_explicit_fill(value: object) -> bool:
564
581
 
565
582
 
566
583
  def _validate_url_field(errors: List[str], field: str, value: object) -> None:
584
+ if not _is_explicit_fill(value):
585
+ return
567
586
  raw = _text(value)
568
587
  parsed = urllib.parse.urlparse(raw)
569
588
  if parsed.scheme not in {"http", "https"} or not parsed.netloc:
@@ -571,6 +590,8 @@ def _validate_url_field(errors: List[str], field: str, value: object) -> None:
571
590
 
572
591
 
573
592
  def _validate_path_field(errors: List[str], field: str, value: object) -> None:
593
+ if not _is_explicit_fill(value):
594
+ return
574
595
  raw = _text(value)
575
596
  if not raw.startswith("/"):
576
597
  errors.append(f"{field} must start with '/'")
@@ -582,6 +603,41 @@ def _require_explicit_field(missing: List[str], field: str, value: object) -> No
582
603
  missing.append(f"{field} (must be explicitly filled, not blank/TODO)")
583
604
 
584
605
 
606
+ def _has_secret_reference(section_cfg: dict, field: str) -> bool:
607
+ return _is_explicit_fill(section_cfg.get(field)) or _is_explicit_fill(section_cfg.get(f"{field}_env"))
608
+
609
+
610
+ def _require_secret_reference(missing: List[str], section_name: str, section_cfg: dict, field: str) -> None:
611
+ if not _has_secret_reference(section_cfg, field):
612
+ missing.append(
613
+ f"{section_name}.{field} or {section_name}.{field}_env "
614
+ "(must be explicitly filled, not blank/TODO)"
615
+ )
616
+
617
+
618
+ def _resolve_secret(section_name: str, section_cfg: dict, field: str) -> str:
619
+ direct_value = section_cfg.get(field)
620
+ if _is_explicit_fill(direct_value):
621
+ return _text(direct_value)
622
+
623
+ env_field = f"{field}_env"
624
+ env_name = _text(section_cfg.get(env_field))
625
+ if _is_explicit_fill(env_name):
626
+ env_value = os.environ.get(env_name, "")
627
+ if _is_explicit_fill(env_value):
628
+ return _text(env_value)
629
+ raise APError(
630
+ f"Missing secret value for {section_name}.{field}. "
631
+ f"Set environment variable {env_name} declared by {section_name}.{env_field}, "
632
+ f"or fill {section_name}.{field}."
633
+ )
634
+
635
+ raise APError(
636
+ f"Missing {section_name}.{field}. Fill {section_name}.{field} "
637
+ f"or declare {section_name}.{env_field}."
638
+ )
639
+
640
+
585
641
  def _run_git_diff_check(repo: Path, cfg: dict) -> None:
586
642
  print("[diff-check] git diff --check")
587
643
  run(["git", "diff", "--check"], cwd=repo)
@@ -603,7 +659,9 @@ def cmd_run(args: argparse.Namespace) -> None:
603
659
  "Edit docs/ENGINEERING.md frontmatter. "
604
660
  f"Available: {', '.join(commands.keys()) or '(none)'}"
605
661
  )
606
- cmd = str(commands[name])
662
+ cmd = str(commands.get(name) or "").strip()
663
+ if not cmd:
664
+ raise APError(f"Command is blank: commands.{name}. Edit docs/ENGINEERING.md frontmatter.")
607
665
  print(f"[run] {name}: {cmd}")
608
666
  run_shell(cmd, cwd=repo)
609
667
  print(f"[run] OK: {name}")
@@ -720,15 +778,15 @@ def cmd_verify_target(args: argparse.Namespace) -> None:
720
778
  frontend_headers: dict[str, str] = {}
721
779
  if args.backend_basic_auth:
722
780
  user = str(target_cfg.get("backend_username") or "").strip()
723
- password = str(target_cfg.get("backend_password") or "").strip()
724
- if not user or not password:
725
- raise APError("Missing target_env.backend_username / target_env.backend_password for backend basic auth.")
781
+ if not user:
782
+ raise APError("Missing target_env.backend_username for backend basic auth.")
783
+ password = _resolve_secret("target_env", target_cfg, "backend_password")
726
784
  backend_headers = _basic_auth_header(user, password)
727
785
  if args.frontend_basic_auth:
728
786
  user = str(target_cfg.get("frontend_username") or "").strip()
729
- password = str(target_cfg.get("frontend_password") or "").strip()
730
- if not user or not password:
731
- raise APError("Missing target_env.frontend_username / target_env.frontend_password for frontend basic auth.")
787
+ if not user:
788
+ raise APError("Missing target_env.frontend_username for frontend basic auth.")
789
+ password = _resolve_secret("target_env", target_cfg, "frontend_password")
732
790
  frontend_headers = _basic_auth_header(user, password)
733
791
 
734
792
  for path in args.backend_path or []:
@@ -792,7 +850,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
792
850
  runtime_cfg = (cfg.get("runtime") or {})
793
851
 
794
852
  missing: List[str] = []
795
- warnings: List[str] = []
853
+ validation_errors: List[str] = []
796
854
 
797
855
  mode = str(workflow_cfg.get("mode") or "dev").strip().lower()
798
856
  if mode not in {"dev", "verify"}:
@@ -809,25 +867,25 @@ def cmd_doctor(args: argparse.Namespace) -> None:
809
867
  _require_explicit_field(missing, "target_env.name", target_cfg.get("name"))
810
868
  _require_explicit_field(missing, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
811
869
  _require_explicit_field(missing, "target_env.frontend_username", target_cfg.get("frontend_username"))
812
- _require_explicit_field(missing, "target_env.frontend_password", target_cfg.get("frontend_password"))
870
+ _require_secret_reference(missing, "target_env", target_cfg, "frontend_password")
813
871
  _require_explicit_field(missing, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
814
872
  _require_explicit_field(missing, "target_env.backend_username", target_cfg.get("backend_username"))
815
- _require_explicit_field(missing, "target_env.backend_password", target_cfg.get("backend_password"))
873
+ _require_secret_reference(missing, "target_env", target_cfg, "backend_password")
816
874
  _require_explicit_field(missing, "target_env.backend_root_username", target_cfg.get("backend_root_username"))
817
- _require_explicit_field(missing, "target_env.backend_root_password", target_cfg.get("backend_root_password"))
875
+ _require_secret_reference(missing, "target_env", target_cfg, "backend_root_password")
818
876
  _require_explicit_field(missing, "target_env.health_base_url", target_cfg.get("health_base_url"))
819
877
  _require_explicit_field(missing, "target_env.health_path", target_cfg.get("health_path"))
820
878
 
821
879
  _require_explicit_field(missing, "jenkins.base_url", jenkins_cfg.get("base_url"))
822
880
  _require_explicit_field(missing, "jenkins.ui_username", jenkins_cfg.get("ui_username"))
823
- _require_explicit_field(missing, "jenkins.ui_password", jenkins_cfg.get("ui_password"))
881
+ _require_secret_reference(missing, "jenkins", jenkins_cfg, "ui_password")
824
882
  _require_explicit_field(missing, "jenkins.job_url", jenkins_cfg.get("job_url"))
825
883
  _require_explicit_field(missing, "jenkins.trigger_branch", jenkins_cfg.get("trigger_branch"))
826
884
  _require_explicit_field(missing, "jenkins.image_repository", jenkins_cfg.get("image_repository"))
827
885
  _require_explicit_field(missing, "jenkins.image_tag_strategy", jenkins_cfg.get("image_tag_strategy"))
828
886
  _require_explicit_field(missing, "jenkins.deploy_env", jenkins_cfg.get("deploy_env"))
829
887
  _require_explicit_field(missing, "jenkins.api_user", jenkins_cfg.get("api_user"))
830
- _require_explicit_field(missing, "jenkins.api_password", jenkins_cfg.get("api_password"))
888
+ _require_secret_reference(missing, "jenkins", jenkins_cfg, "api_password")
831
889
 
832
890
  repo_docs = {
833
891
  "docs.taskbook": Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md"))),
@@ -837,28 +895,27 @@ def cmd_doctor(args: argparse.Namespace) -> None:
837
895
  }
838
896
  for key, path in repo_docs.items():
839
897
  if not path.exists():
840
- warnings.append(f"{key} missing on disk: {path}")
898
+ validation_errors.append(f"{key} missing on disk: {path}")
841
899
 
842
- _validate_url_field(warnings, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
843
- _validate_url_field(warnings, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
844
- _validate_url_field(warnings, "target_env.health_base_url", target_cfg.get("health_base_url"))
845
- _validate_path_field(warnings, "target_env.health_path", target_cfg.get("health_path"))
846
- _validate_url_field(warnings, "jenkins.base_url", jenkins_cfg.get("base_url"))
847
- _validate_url_field(warnings, "jenkins.job_url", jenkins_cfg.get("job_url"))
900
+ _validate_url_field(validation_errors, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
901
+ _validate_url_field(validation_errors, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
902
+ _validate_url_field(validation_errors, "target_env.health_base_url", target_cfg.get("health_base_url"))
903
+ _validate_path_field(validation_errors, "target_env.health_path", target_cfg.get("health_path"))
904
+ _validate_url_field(validation_errors, "jenkins.base_url", jenkins_cfg.get("base_url"))
905
+ _validate_url_field(validation_errors, "jenkins.job_url", jenkins_cfg.get("job_url"))
848
906
 
849
907
  runtime_enabled = any(str(runtime_cfg.get(key) or "").strip() for key in ["docker_compose_file", "docker_service", "health_base_url", "health_path"])
850
908
  if runtime_enabled and not str(runtime_cfg.get("docker_compose_file") or "").strip():
851
- warnings.append("runtime config is partially enabled but runtime.docker_compose_file is missing")
909
+ validation_errors.append("runtime config is partially enabled but runtime.docker_compose_file is missing")
852
910
 
853
911
  try:
854
912
  timeout_s = int(jenkins_cfg.get("deploy_timeout_sec") or 0)
855
913
  if timeout_s <= 0:
856
- warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
914
+ validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
857
915
  except Exception:
858
- warnings.append("jenkins.deploy_timeout_sec must be a positive integer")
916
+ validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
859
917
 
860
- if warnings:
861
- missing.extend([f"invalid {item}" for item in warnings])
918
+ missing.extend(validation_errors)
862
919
 
863
920
  if missing:
864
921
  raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
package/cli/src/index.js CHANGED
@@ -9,17 +9,33 @@ function die(msg){
9
9
  process.exit(1);
10
10
  }
11
11
 
12
+ function takeValue(rest, index, flag){
13
+ const value = rest[index + 1];
14
+ if (!value || value.startsWith("--")) die(`${flag} requires a value`);
15
+ return value;
16
+ }
17
+
12
18
  function parseArgs(argv){
13
19
  const args = { cmd: null, ai: null, mode: "project", dest: null, force: false };
14
20
  const [,, cmd, ...rest] = argv;
15
- args.cmd = cmd ?? "help";
21
+ args.cmd = (!cmd || cmd === "-h" || cmd === "--help") ? "help" : cmd;
16
22
  for (let i = 0; i < rest.length; i++) {
17
23
  const a = rest[i];
18
- if (a === "--ai") args.ai = rest[++i];
19
- else if (a === "--mode") args.mode = rest[++i];
20
- else if (a === "--dest") args.dest = rest[++i];
24
+ if (a === "--ai") {
25
+ args.ai = takeValue(rest, i, a);
26
+ i += 1;
27
+ }
28
+ else if (a === "--mode") {
29
+ args.mode = takeValue(rest, i, a);
30
+ i += 1;
31
+ }
32
+ else if (a === "--dest") {
33
+ args.dest = takeValue(rest, i, a);
34
+ i += 1;
35
+ }
21
36
  else if (a === "--force") args.force = true;
22
37
  else if (a === "-h" || a === "--help") args.cmd = "help";
38
+ else die(`unknown argument: ${a}`);
23
39
  }
24
40
  return args;
25
41
  }
@@ -62,6 +78,18 @@ function resolveTargetDir(ai, mode, destOverride){
62
78
  die(`unknown ai: ${ai}`);
63
79
  }
64
80
 
81
+ function resolveAgentsDir(mode, destOverride, multiTarget){
82
+ if (destOverride) {
83
+ return multiTarget
84
+ ? path.join(destOverride, "agents")
85
+ : path.join(destOverride, ".agents", "agents");
86
+ }
87
+ if (mode !== "project" && mode !== "global") die(`--mode must be 'project' or 'global'`);
88
+ return mode === "project"
89
+ ? path.join(projectRoot(), ".agents", "agents")
90
+ : path.join(os.homedir(), ".agents", "agents");
91
+ }
92
+
65
93
  function main(){
66
94
  const args = parseArgs(process.argv);
67
95
 
@@ -89,7 +117,9 @@ Examples:
89
117
 
90
118
  const here = path.dirname(fileURLToPath(import.meta.url));
91
119
  const assetSkill = path.resolve(here, "..", "assets", "skill");
120
+ const assetAgents = path.resolve(here, "..", "assets", "agents");
92
121
  if (!exists(assetSkill)) die(`missing assets at ${assetSkill}`);
122
+ if (!exists(assetAgents)) die(`missing assets at ${assetAgents}`);
93
123
 
94
124
  for (const t of targets) {
95
125
  const dstOverride = args.dest
@@ -102,6 +132,16 @@ Examples:
102
132
  }
103
133
  copyDir(assetSkill, dst);
104
134
  console.log(`[autocoding] installed skill to: ${dst}`);
135
+
136
+ if (t === "codex") {
137
+ const agentsDst = resolveAgentsDir(args.mode, args.dest, targets.length > 1);
138
+ if (exists(agentsDst)) {
139
+ if (!args.force) die(`target exists: ${agentsDst}\nRe-run with --force to overwrite.`);
140
+ rmrf(agentsDst);
141
+ }
142
+ copyDir(assetAgents, agentsDst);
143
+ console.log(`[autocoding] installed Codex agents to: ${agentsDst}`);
144
+ }
105
145
  }
106
146
 
107
147
  console.log("[autocoding] done.");
@@ -5,7 +5,11 @@ import { fileURLToPath } from "node:url";
5
5
  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
6
6
  const srcSkill = path.join(repoRoot, "src", "auto-coding-skill");
7
7
  const dstSkill = path.join(repoRoot, "cli", "assets", "skill");
8
+ const srcAgents = path.join(repoRoot, "src", "agents");
9
+ const dstAgents = path.join(repoRoot, "cli", "assets", "agents");
10
+ const checkOnly = process.argv.includes("--check");
8
11
 
12
+ function exists(p){ try { fs.accessSync(p); return true; } catch { return false; } }
9
13
  function rmrf(p){ fs.rmSync(p, { recursive:true, force:true }); }
10
14
  function shouldSkip(name){
11
15
  return name === "__pycache__" || name === ".DS_Store" || name.endsWith(".pyc");
@@ -21,6 +25,58 @@ function copyDir(src, dst){
21
25
  }
22
26
  }
23
27
 
28
+ function listFiles(root, base = root){
29
+ if (!exists(root)) return [];
30
+ const out = [];
31
+ for (const ent of fs.readdirSync(root, { withFileTypes:true })) {
32
+ if (shouldSkip(ent.name)) continue;
33
+ const p = path.join(root, ent.name);
34
+ if (ent.isDirectory()) out.push(...listFiles(p, base));
35
+ else out.push(path.relative(base, p));
36
+ }
37
+ return out.sort();
38
+ }
39
+
40
+ function compareDirs(src, dst, label){
41
+ const diffs = [];
42
+ const srcFiles = listFiles(src);
43
+ const dstFiles = listFiles(dst);
44
+ const srcSet = new Set(srcFiles);
45
+ const dstSet = new Set(dstFiles);
46
+
47
+ for (const rel of srcFiles) {
48
+ if (!dstSet.has(rel)) {
49
+ diffs.push(`${label}: missing asset ${rel}`);
50
+ continue;
51
+ }
52
+ const srcBuf = fs.readFileSync(path.join(src, rel));
53
+ const dstBuf = fs.readFileSync(path.join(dst, rel));
54
+ if (!srcBuf.equals(dstBuf)) diffs.push(`${label}: stale asset ${rel}`);
55
+ }
56
+ for (const rel of dstFiles) {
57
+ if (!srcSet.has(rel)) diffs.push(`${label}: extra asset ${rel}`);
58
+ }
59
+ return diffs;
60
+ }
61
+
62
+ if (checkOnly) {
63
+ const diffs = [
64
+ ...compareDirs(srcSkill, dstSkill, "skill"),
65
+ ...compareDirs(srcAgents, dstAgents, "agents"),
66
+ ];
67
+ if (diffs.length > 0) {
68
+ console.error("[sync-assets] assets are out of sync:");
69
+ for (const diff of diffs) console.error(`- ${diff}`);
70
+ console.error("[sync-assets] run: npm run sync-assets");
71
+ process.exit(1);
72
+ }
73
+ console.log("[sync-assets] OK: cli assets match src");
74
+ process.exit(0);
75
+ }
76
+
24
77
  rmrf(dstSkill);
25
78
  copyDir(srcSkill, dstSkill);
79
+ rmrf(dstAgents);
80
+ copyDir(srcAgents, dstAgents);
26
81
  console.log("[sync-assets] updated cli/assets/skill from src/auto-coding-skill");
82
+ console.log("[sync-assets] updated cli/assets/agents from src/agents");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "2.0.1",
3
+ "version": "2.0.3",
4
4
  "description": "CLI installer for auto-coding-skill (Claude Code + Codex CLI) with Go fullstack + Jenkins workflow support.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -9,11 +9,13 @@
9
9
  "files": [
10
10
  "cli/src",
11
11
  "cli/assets/skill",
12
+ "cli/assets/agents",
12
13
  "README.md",
13
14
  "LICENSE"
14
15
  ],
15
16
  "scripts": {
16
- "test": "node -c cli/src/index.js && python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py', 'cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py && find src cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
17
+ "test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && python3 -c \"import ast, pathlib; files = ['src/auto-coding-skill/scripts/ap.py', 'src/auto-coding-skill/scripts/core.py', 'src/auto-coding-skill/scripts/http_checks.py', 'cli/assets/skill/scripts/ap.py', 'cli/assets/skill/scripts/core.py', 'cli/assets/skill/scripts/http_checks.py']; [ast.parse(pathlib.Path(rel).read_text(encoding='utf-8'), filename=rel, feature_version=(3, 11)) for rel in files]; print('python311-grammar-ok')\" && python3 -m py_compile src/auto-coding-skill/scripts/ap.py src/auto-coding-skill/scripts/core.py src/auto-coding-skill/scripts/http_checks.py cli/assets/skill/scripts/ap.py cli/assets/skill/scripts/core.py cli/assets/skill/scripts/http_checks.py && python3 -c \"import pathlib, tomllib; files = sorted(pathlib.Path('src/agents').glob('*.toml')) + sorted(pathlib.Path('cli/assets/agents').glob('*.toml')); [tomllib.loads(path.read_text(encoding='utf-8')) for path in files]; print('agent-toml-ok')\" && npm run check:assets && find src cli -type d -name '__pycache__' -prune -exec rm -rf {} +",
18
+ "check:assets": "node cli/src/sync-assets.js --check",
17
19
  "sync-assets": "node cli/src/sync-assets.js",
18
20
  "release:check": "npm run sync-assets && npm run test && npm pack --dry-run"
19
21
  },