@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 +50 -21
- package/cli/assets/agents/browser-debugger.toml +30 -0
- package/cli/assets/agents/docs-researcher.toml +21 -0
- package/cli/assets/agents/explorer.toml +27 -0
- package/cli/assets/agents/fixer.toml +25 -0
- package/cli/assets/agents/reviewer.toml +22 -0
- package/cli/assets/skill/SKILL.md +29 -19
- package/cli/assets/skill/data/templates/ENGINEERING.md +89 -41
- package/cli/assets/skill/data/templates/bridges/CLAUDE.md +2 -2
- package/cli/assets/skill/data/templates/bridges/CODEX.md +2 -2
- package/cli/assets/skill/scripts/ap.py +104 -47
- package/cli/src/index.js +44 -4
- package/cli/src/sync-assets.js +56 -0
- package/package.json +4 -2
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
|
|
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
|
-
-
|
|
176
|
-
-
|
|
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
|
-
-
|
|
181
|
-
-
|
|
182
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
23
|
+
Use the most direct authoritative capability for each task:
|
|
24
24
|
|
|
25
|
-
1)
|
|
26
|
-
2)
|
|
27
|
-
3)
|
|
28
|
-
4)
|
|
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
|
-
|
|
38
|
+
Use `.agents/agents` role templates as the default collaboration model for Codex installs:
|
|
33
39
|
|
|
34
|
-
1)
|
|
35
|
-
2)
|
|
36
|
-
3)
|
|
37
|
-
4)
|
|
38
|
-
5)
|
|
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
|
-
|
|
36
|
+
frontend_password_env: ""
|
|
37
37
|
backend_base_url: ""
|
|
38
38
|
backend_username: ""
|
|
39
|
-
|
|
39
|
+
backend_password_env: ""
|
|
40
40
|
backend_root_username: ""
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
|
100
|
+
- `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
|
|
101
|
+
- `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
|
|
102
102
|
|
|
103
103
|
字段说明:
|
|
104
|
-
- `target_env.backend_username`
|
|
105
|
-
- `target_env.backend_root_username`
|
|
106
|
-
- `target_env.frontend_username`
|
|
107
|
-
- `jenkins.ui_username`
|
|
108
|
-
- `jenkins.api_user`
|
|
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
|
-
|
|
167
|
-
2) 已安装 skills
|
|
168
|
-
3) plugins / apps / connectors
|
|
169
|
-
4) shell / 手工实现
|
|
167
|
+
默认路由:
|
|
170
168
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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
|
-
|
|
208
|
+
默认使用 `.agents/agents` 中的角色模型来拆解任务;只有在当前客户端明确提供并允许子代理/多代理工具时,才实际并行派发。若运行时策略不允许子代理,则由主 agent 按同一角色顺序串行完成,不假装并行。
|
|
181
209
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
3
|
-
|
|
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
|
-
|
|
3
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
64
|
+
credential_pairs = [
|
|
65
|
+
("api_user", "api_password"),
|
|
66
|
+
("ui_username", "ui_password"),
|
|
66
67
|
]
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
724
|
-
|
|
725
|
-
|
|
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
|
-
|
|
730
|
-
|
|
731
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
898
|
+
validation_errors.append(f"{key} missing on disk: {path}")
|
|
841
899
|
|
|
842
|
-
_validate_url_field(
|
|
843
|
-
_validate_url_field(
|
|
844
|
-
_validate_url_field(
|
|
845
|
-
_validate_path_field(
|
|
846
|
-
_validate_url_field(
|
|
847
|
-
_validate_url_field(
|
|
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
|
-
|
|
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
|
-
|
|
914
|
+
validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
|
|
857
915
|
except Exception:
|
|
858
|
-
|
|
916
|
+
validation_errors.append("jenkins.deploy_timeout_sec must be a positive integer")
|
|
859
917
|
|
|
860
|
-
|
|
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
|
|
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")
|
|
19
|
-
|
|
20
|
-
|
|
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.");
|
package/cli/src/sync-assets.js
CHANGED
|
@@ -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.
|
|
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
|
},
|