@hongmaple0820/scale-engine 0.24.0 → 0.26.0
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/LICENSE +15 -15
- package/README.en.md +336 -304
- package/README.md +500 -475
- package/dist/adapters/AiderAdapter.js +52 -52
- package/dist/adapters/AntigravityAdapter.d.ts +4 -0
- package/dist/adapters/AntigravityAdapter.js +21 -0
- package/dist/adapters/AntigravityAdapter.js.map +1 -0
- package/dist/adapters/ClaudeCodeAdapter.d.ts +4 -1
- package/dist/adapters/ClaudeCodeAdapter.js +34 -34
- package/dist/adapters/ClaudeCodeAdapter.js.map +1 -1
- package/dist/adapters/ClineAdapter.d.ts +4 -0
- package/dist/adapters/ClineAdapter.js +20 -0
- package/dist/adapters/ClineAdapter.js.map +1 -0
- package/dist/adapters/CodexAdapter.js +28 -28
- package/dist/adapters/CursorAdapter.js +26 -26
- package/dist/adapters/DeepSeekTuiAdapter.js +97 -97
- package/dist/adapters/DoubaoAdapter.js +33 -33
- package/dist/adapters/GeminiAdapter.js +26 -26
- package/dist/adapters/GenericProjectAgentAdapter.d.ts +29 -0
- package/dist/adapters/GenericProjectAgentAdapter.js +204 -0
- package/dist/adapters/GenericProjectAgentAdapter.js.map +1 -0
- package/dist/adapters/HermesAdapter.js +26 -26
- package/dist/adapters/JCodeAdapter.d.ts +4 -0
- package/dist/adapters/JCodeAdapter.js +19 -0
- package/dist/adapters/JCodeAdapter.js.map +1 -0
- package/dist/adapters/KiloCodeAdapter.d.ts +4 -0
- package/dist/adapters/KiloCodeAdapter.js +20 -0
- package/dist/adapters/KiloCodeAdapter.js.map +1 -0
- package/dist/adapters/KimiAdapter.js +32 -32
- package/dist/adapters/KiroAdapter.js +26 -26
- package/dist/adapters/OpenClawAdapter.js +26 -26
- package/dist/adapters/OpenCodeAdapter.js +26 -26
- package/dist/adapters/QCoderAdapter.js +26 -26
- package/dist/adapters/QoderAdapter.d.ts +4 -0
- package/dist/adapters/QoderAdapter.js +21 -0
- package/dist/adapters/QoderAdapter.js.map +1 -0
- package/dist/adapters/TraeAdapter.js +26 -26
- package/dist/adapters/VSCAdapter.js +26 -26
- package/dist/adapters/WindsurfAdapter.js +32 -32
- package/dist/adapters/WorkBuddyAdapter.js +26 -26
- package/dist/adapters/index.d.ts +5 -0
- package/dist/adapters/index.js +15 -0
- package/dist/adapters/index.js.map +1 -1
- package/dist/api/cli.js +226 -48
- package/dist/api/cli.js.map +1 -1
- package/dist/api/doctor.js +10 -3
- package/dist/api/doctor.js.map +1 -1
- package/dist/api/quickstart.js +7 -1
- package/dist/api/quickstart.js.map +1 -1
- package/dist/artifact/sqliteStore.js +89 -89
- package/dist/artifact/types.d.ts +1 -1
- package/dist/cli/phaseCommands.js +45 -45
- package/dist/context/AntiPatternRegistry.js +20 -20
- package/dist/context/ContextBuilder.js +155 -155
- package/dist/evolution/EvolutionEngine.js +31 -31
- package/dist/evolution/EvolutionEvaluator.d.ts +2 -0
- package/dist/evolution/EvolutionEvaluator.js +7 -1
- package/dist/evolution/EvolutionEvaluator.js.map +1 -1
- package/dist/fsm/FSMAgentBridge.js +11 -11
- package/dist/hooks/HookGeneratorEnhanced.js +218 -218
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/knowledge/SQLiteKnowledgeBase.js +28 -28
- package/dist/memory/MemoryBrain.d.ts +1 -0
- package/dist/memory/MemoryBrain.js +55 -52
- package/dist/memory/MemoryBrain.js.map +1 -1
- package/dist/memory/MemoryFabric.d.ts +13 -1
- package/dist/memory/MemoryFabric.js +35 -0
- package/dist/memory/MemoryFabric.js.map +1 -1
- package/dist/memory/MemoryProviders.d.ts +111 -0
- package/dist/memory/MemoryProviders.js +385 -0
- package/dist/memory/MemoryProviders.js.map +1 -0
- package/dist/memory/index.d.ts +1 -0
- package/dist/memory/index.js +1 -0
- package/dist/memory/index.js.map +1 -1
- package/dist/output/GovernanceDashboard.js +44 -44
- package/dist/output/HTMLArtifactLayer.js +31 -31
- package/dist/prompts/VibeTemplateGallery.js +121 -121
- package/dist/skills/SkillDiscovery.js +12 -1
- package/dist/skills/SkillDiscovery.js.map +1 -1
- package/dist/skills/SkillRadar.js +20 -0
- package/dist/skills/SkillRadar.js.map +1 -1
- package/dist/skills/SkillRepository.d.ts +9 -1
- package/dist/skills/SkillRepository.js +70 -0
- package/dist/skills/SkillRepository.js.map +1 -1
- package/dist/skills/routing/SkillPlanner.js +40 -40
- package/dist/workflow/EngineeringStandards.js +62 -62
- package/dist/workflow/GovernanceTemplatePacks.d.ts +1 -1
- package/dist/workflow/GovernanceTemplatePacks.js +1990 -162
- package/dist/workflow/GovernanceTemplatePacks.js.map +1 -1
- package/dist/workflow/GovernanceTemplates.d.ts +2 -0
- package/dist/workflow/GovernanceTemplates.js +1012 -1001
- package/dist/workflow/GovernanceTemplates.js.map +1 -1
- package/dist/workflow/ResourceGovernance.js +16 -16
- package/dist/workflow/TaskArtifactScaffolder.js +10 -10
- package/dist/workflow/UpgradeManager.d.ts +3 -2
- package/dist/workflow/UpgradeManager.js +134 -49
- package/dist/workflow/UpgradeManager.js.map +1 -1
- package/dist/workflow/WorkspaceTopology.js +18 -15
- package/dist/workflow/WorkspaceTopology.js.map +1 -1
- package/docs/CODE_INTELLIGENCE.md +138 -138
- package/docs/CONTEXT_BUDGET.md +81 -81
- package/docs/EXTERNAL_REFERENCES.md +63 -0
- package/docs/GITLAB_FLOW.md +125 -125
- package/docs/GOVERNANCE_DASHBOARD.md +64 -64
- package/docs/MEMORY_BRAIN.md +104 -104
- package/docs/MEMORY_FABRIC.md +134 -107
- package/docs/README.md +79 -68
- package/docs/RUNTIME_EVIDENCE.md +101 -101
- package/docs/SKILL-REPOSITORY.md +57 -0
- package/docs/SKILL_RADAR.md +122 -115
- package/docs/THIRD_PARTY_SKILLS.md +57 -0
- package/docs/WORKFLOW_EVAL.md +151 -151
- package/docs/guides/DEVELOPMENT_WORKFLOW.md +80 -0
- package/docs/guides/GETTING_STARTED.md +50 -0
- package/docs/start/README.md +78 -72
- package/docs/start/agent-governance-demo.md +107 -107
- package/docs/start/quickstart.md +137 -127
- package/docs/start/workflow-upgrade.md +32 -8
- package/docs/workflow/README.md +67 -0
- package/docs/workflow/node-library.md +52 -0
- package/docs/workflow/templates/api-contract.md +29 -0
- package/docs/workflow/templates/architecture-review.md +23 -0
- package/docs/workflow/templates/db-change-plan.md +20 -0
- package/docs/workflow/templates/docs-impact.md +17 -0
- package/docs/workflow/templates/e2e-plan.md +20 -0
- package/docs/workflow/templates/explore.md +16 -0
- package/docs/workflow/templates/github-actions-scale-preflight.yml +32 -0
- package/docs/workflow/templates/mini-prd.md +16 -0
- package/docs/workflow/templates/plan.md +37 -0
- package/docs/workflow/templates/pre-push-scale-preflight.sh +8 -0
- package/docs/workflow/templates/product-smoke.md +61 -0
- package/docs/workflow/templates/reality-check.md +28 -0
- package/docs/workflow/templates/resource-cleanup.md +17 -0
- package/docs/workflow/templates/resource-impact.md +25 -0
- package/docs/workflow/templates/review.md +12 -0
- package/docs/workflow/templates/runtime.md +23 -0
- package/docs/workflow/templates/security-review.md +26 -0
- package/docs/workflow/templates/skill-evidence.md +33 -0
- package/docs/workflow/templates/skill-plan.md +39 -0
- package/docs/workflow/templates/spec.md +17 -0
- package/docs/workflow/templates/standards-impact.md +28 -0
- package/docs/workflow/templates/summary.md +16 -0
- package/docs/workflow/templates/tasks.md +8 -0
- package/docs/workflow/templates/ui-spec.md +29 -0
- package/docs/workflow/templates/verification.md +20 -0
- package/docs/workflow/templates/visual-review.md +20 -0
- package/examples/demo-projects/agent-governance-demo/CONTEXT.md +14 -14
- package/examples/demo-projects/agent-governance-demo/README.md +48 -48
- package/examples/demo-projects/agent-governance-demo/docs/CONTEXT-MAP.md +14 -14
- package/examples/demo-projects/agent-governance-demo/package.json +22 -21
- package/examples/demo-projects/agent-governance-demo/src/oauth-state.ts +39 -39
- package/examples/demo-projects/agent-governance-demo/tests/oauth-state.test.ts +52 -52
- package/package.json +88 -75
package/docs/start/quickstart.md
CHANGED
|
@@ -1,127 +1,137 @@
|
|
|
1
|
-
# 3 分钟快速开始
|
|
2
|
-
|
|
3
|
-
目标:在一个空目录中安装 SCALE 治理工作流,并看到可验证的项目产物。
|
|
4
|
-
|
|
5
|
-
## 前置条件
|
|
6
|
-
|
|
7
|
-
- Node.js 20 或更高版本。
|
|
8
|
-
- 已安装 npm。
|
|
9
|
-
- Windows PowerShell、Git Bash、macOS/Linux shell 都可以执行。
|
|
10
|
-
|
|
11
|
-
## 1. 安装 CLI
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
npm install -g @hongmaple0820/scale-engine
|
|
15
|
-
scale --version
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
如果你在开发 `scale-engine` 本仓库,也可以用本地构建后的命令:
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
node E:/project/scale-engine/dist/api/cli.js --help
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
## 2. 初始化一个空项目
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
mkdir scale-demo
|
|
28
|
-
cd scale-demo
|
|
29
|
-
scale init --governance-pack standard
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
这一步会生成:
|
|
33
|
-
|
|
34
|
-
```text
|
|
35
|
-
.scale/
|
|
36
|
-
docs/
|
|
37
|
-
scripts/
|
|
38
|
-
AGENTS.md 或对应 Agent 入口文档
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
重点看这些文件:
|
|
42
|
-
|
|
43
|
-
| 文件 | 用途 |
|
|
44
|
-
| --- | --- |
|
|
45
|
-
| `.scale/verification.json` | 本地验证 profile 和服务矩阵 |
|
|
46
|
-
| `.scale/skills.json` | Agent 应该如何选择 skills,以及哪些需要证据 |
|
|
47
|
-
| `.scale/tools.json` | CLI、MCP、浏览器、桌面自动化等工具使用策略 |
|
|
48
|
-
| `.scale/resource-policy.json` | 文档、报告、截图、脚本、临时产物的生命周期规则 |
|
|
49
|
-
| `.scale/engineering-standards.json` | 日志、安全、ORM、框架、测试、部署等工程规范 |
|
|
50
|
-
| `docs/workflow/templates/` | M/L 任务使用的标准 artifact 模板 |
|
|
51
|
-
|
|
52
|
-
## 3. 跑第一轮本地检查
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
scale preflight --preflight-profile quick
|
|
56
|
-
scale status
|
|
57
|
-
scale assets scan --dir .
|
|
58
|
-
scale standards scan --dir .
|
|
59
|
-
scale runtime doctor --level S
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
预期效果:
|
|
63
|
-
|
|
64
|
-
- `preflight` 能说明当前治理文件是否完整。
|
|
65
|
-
- `status` 会告诉 Agent 下一步应该做什么。
|
|
66
|
-
- `assets scan` 会把文档、模板、脚本、报告等资源分类。
|
|
67
|
-
- `standards scan` 会扫描日志噪音、敏感信息、危险输入、测试和架构风险。
|
|
68
|
-
- `runtime doctor` 会检查本地运行时证据目录和最终交付证据状态。
|
|
69
|
-
|
|
70
|
-
## 4. 建立第一个任务上下文
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
scale context init --name "Scale Demo"
|
|
74
|
-
scale runtime start --session-id 2026-05-18-oauth-hardening --task-id 2026-05-18-oauth-hardening --level M --agent codex
|
|
75
|
-
scale context grill --task-id 2026-05-18-oauth-hardening --task "加固 OAuth callback"
|
|
76
|
-
scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在 state 过期时返回 500"
|
|
77
|
-
scale tdd slice --task-id 2026-05-18-oauth-hardening --behavior "拒绝过期 OAuth state" --public-interface "GET /oauth/callback" --failing-test "expired state returns 401" --test-file tests/oauth.test.ts --impl-files src/oauth.ts
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
这些命令的目的不是替代人类判断,而是把 Agent 必须做的思考显式记录下来:
|
|
81
|
-
|
|
82
|
-
- `context grill`:逼 Agent 先澄清上下文、成功标准和风险。
|
|
83
|
-
- `diagnose plan`:遇到问题先诊断,不允许盲修。
|
|
84
|
-
- `tdd slice`:把行为、公共接口、失败测试和实现文件绑定成一个可检查切片。
|
|
85
|
-
- `runtime start`:建立会话 ledger,后续命令、工具和验证证据可以绑定到同一个任务。
|
|
86
|
-
|
|
87
|
-
完成真实验证后记录运行时证据:
|
|
88
|
-
|
|
89
|
-
```bash
|
|
90
|
-
scale runtime record --title "quick preflight" --kind command --status passed --command "scale preflight --preflight-profile quick" --exit-code 0 --summary "quick preflight passed"
|
|
91
|
-
scale runtime final-check --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --level M
|
|
92
|
-
scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M --budget 4000
|
|
93
|
-
scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
`memory pack` 用来恢复上下文,`memory settle` 用来在任务结束后生成学习候选。候选位于 `.scale/memory/learning-candidates/`,默认本地保留,确认稳定后再人工提升到知识库、规范或模块文档。
|
|
97
|
-
|
|
98
|
-
## 5. 生成 HTML 交付视图
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
102
|
-
scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
103
|
-
scale artifact open --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
规则:
|
|
107
|
-
|
|
108
|
-
- Markdown 是长期维护源文件。
|
|
109
|
-
- HTML 是给评审、对比、状态汇报、交付和发版使用的可视化产物。
|
|
110
|
-
- `artifact doctor` 会检查 HTML 是否可追溯、是否引用远程资源、是否可能包含敏感信息。
|
|
111
|
-
|
|
112
|
-
## 6. 下一步
|
|
113
|
-
|
|
114
|
-
如果你只是试用,到这里已经能看到 SCALE 的价值:它把 Agent 的工作过程变成了可以审计的证据链。
|
|
115
|
-
|
|
116
|
-
如果你要接入真实项目,按项目类型选择 governance pack:
|
|
117
|
-
|
|
118
|
-
```bash
|
|
119
|
-
scale init --governance-pack node-library
|
|
120
|
-
scale init --governance-pack frontend-app
|
|
121
|
-
scale init --governance-pack go-service-matrix
|
|
122
|
-
scale init --governance-pack moe-workspace
|
|
123
|
-
scale init --governance-pack resource-governance
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
1
|
+
# 3 分钟快速开始
|
|
2
|
+
|
|
3
|
+
目标:在一个空目录中安装 SCALE 治理工作流,并看到可验证的项目产物。
|
|
4
|
+
|
|
5
|
+
## 前置条件
|
|
6
|
+
|
|
7
|
+
- Node.js 20 或更高版本。
|
|
8
|
+
- 已安装 npm。
|
|
9
|
+
- Windows PowerShell、Git Bash、macOS/Linux shell 都可以执行。
|
|
10
|
+
|
|
11
|
+
## 1. 安装 CLI
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g @hongmaple0820/scale-engine
|
|
15
|
+
scale --version
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
如果你在开发 `scale-engine` 本仓库,也可以用本地构建后的命令:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
node E:/project/scale-engine/dist/api/cli.js --help
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## 2. 初始化一个空项目
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
mkdir scale-demo
|
|
28
|
+
cd scale-demo
|
|
29
|
+
scale init --governance-pack standard
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
这一步会生成:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
.scale/
|
|
36
|
+
docs/
|
|
37
|
+
scripts/
|
|
38
|
+
AGENTS.md 或对应 Agent 入口文档
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
重点看这些文件:
|
|
42
|
+
|
|
43
|
+
| 文件 | 用途 |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `.scale/verification.json` | 本地验证 profile 和服务矩阵 |
|
|
46
|
+
| `.scale/skills.json` | Agent 应该如何选择 skills,以及哪些需要证据 |
|
|
47
|
+
| `.scale/tools.json` | CLI、MCP、浏览器、桌面自动化等工具使用策略 |
|
|
48
|
+
| `.scale/resource-policy.json` | 文档、报告、截图、脚本、临时产物的生命周期规则 |
|
|
49
|
+
| `.scale/engineering-standards.json` | 日志、安全、ORM、框架、测试、部署等工程规范 |
|
|
50
|
+
| `docs/workflow/templates/` | M/L 任务使用的标准 artifact 模板 |
|
|
51
|
+
|
|
52
|
+
## 3. 跑第一轮本地检查
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
scale preflight --preflight-profile quick
|
|
56
|
+
scale status
|
|
57
|
+
scale assets scan --dir .
|
|
58
|
+
scale standards scan --dir .
|
|
59
|
+
scale runtime doctor --level S
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
预期效果:
|
|
63
|
+
|
|
64
|
+
- `preflight` 能说明当前治理文件是否完整。
|
|
65
|
+
- `status` 会告诉 Agent 下一步应该做什么。
|
|
66
|
+
- `assets scan` 会把文档、模板、脚本、报告等资源分类。
|
|
67
|
+
- `standards scan` 会扫描日志噪音、敏感信息、危险输入、测试和架构风险。
|
|
68
|
+
- `runtime doctor` 会检查本地运行时证据目录和最终交付证据状态。
|
|
69
|
+
|
|
70
|
+
## 4. 建立第一个任务上下文
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
scale context init --name "Scale Demo"
|
|
74
|
+
scale runtime start --session-id 2026-05-18-oauth-hardening --task-id 2026-05-18-oauth-hardening --level M --agent codex
|
|
75
|
+
scale context grill --task-id 2026-05-18-oauth-hardening --task "加固 OAuth callback"
|
|
76
|
+
scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在 state 过期时返回 500"
|
|
77
|
+
scale tdd slice --task-id 2026-05-18-oauth-hardening --behavior "拒绝过期 OAuth state" --public-interface "GET /oauth/callback" --failing-test "expired state returns 401" --test-file tests/oauth.test.ts --impl-files src/oauth.ts
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
这些命令的目的不是替代人类判断,而是把 Agent 必须做的思考显式记录下来:
|
|
81
|
+
|
|
82
|
+
- `context grill`:逼 Agent 先澄清上下文、成功标准和风险。
|
|
83
|
+
- `diagnose plan`:遇到问题先诊断,不允许盲修。
|
|
84
|
+
- `tdd slice`:把行为、公共接口、失败测试和实现文件绑定成一个可检查切片。
|
|
85
|
+
- `runtime start`:建立会话 ledger,后续命令、工具和验证证据可以绑定到同一个任务。
|
|
86
|
+
|
|
87
|
+
完成真实验证后记录运行时证据:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
scale runtime record --title "quick preflight" --kind command --status passed --command "scale preflight --preflight-profile quick" --exit-code 0 --summary "quick preflight passed"
|
|
91
|
+
scale runtime final-check --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --level M
|
|
92
|
+
scale memory pack --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M --budget 4000
|
|
93
|
+
scale memory settle --task-id 2026-05-18-oauth-hardening --session-id 2026-05-18-oauth-hardening --task "继续加固 OAuth callback" --level M
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`memory pack` 用来恢复上下文,`memory settle` 用来在任务结束后生成学习候选。候选位于 `.scale/memory/learning-candidates/`,默认本地保留,确认稳定后再人工提升到知识库、规范或模块文档。
|
|
97
|
+
|
|
98
|
+
## 5. 生成 HTML 交付视图
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
102
|
+
scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
103
|
+
scale artifact open --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
规则:
|
|
107
|
+
|
|
108
|
+
- Markdown 是长期维护源文件。
|
|
109
|
+
- HTML 是给评审、对比、状态汇报、交付和发版使用的可视化产物。
|
|
110
|
+
- `artifact doctor` 会检查 HTML 是否可追溯、是否引用远程资源、是否可能包含敏感信息。
|
|
111
|
+
|
|
112
|
+
## 6. 下一步
|
|
113
|
+
|
|
114
|
+
如果你只是试用,到这里已经能看到 SCALE 的价值:它把 Agent 的工作过程变成了可以审计的证据链。
|
|
115
|
+
|
|
116
|
+
如果你要接入真实项目,按项目类型选择 governance pack:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
scale init --governance-pack node-library
|
|
120
|
+
scale init --governance-pack frontend-app
|
|
121
|
+
scale init --governance-pack go-service-matrix
|
|
122
|
+
scale init --governance-pack moe-workspace
|
|
123
|
+
scale init --governance-pack resource-governance
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
已有项目升级工作流时不要盲目重跑 `scale init`。先走受保护的升级链路:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
scale upgrade check --dir . --lang zh
|
|
130
|
+
scale upgrade plan --dir . --html --lang zh
|
|
131
|
+
scale upgrade apply --dir . --confirm --lang zh
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
需要英文输出时把 `--lang zh` 换成 `--lang en`。干净的 SCALE 受管文件可以自动刷新;已有本地改动的文件会进入人工审阅,不会被自动覆盖。
|
|
135
|
+
|
|
136
|
+
继续阅读 [官方 Demo Walkthrough](agent-governance-demo.md),看一个真实任务如何从需求到验证证据。
|
|
137
|
+
|
|
@@ -17,7 +17,7 @@ SCALE 把更新分成三层:
|
|
|
17
17
|
| 层级 | 命令支持 | 默认行为 |
|
|
18
18
|
| --- | --- | --- |
|
|
19
19
|
| SCALE CLI | `npm install -g @hongmaple0820/scale-engine@latest` | 用户显式安装或升级 |
|
|
20
|
-
| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` |
|
|
20
|
+
| 生成的工作流文件 | `scale upgrade check/plan/apply/rollback` | 先安全检查和生成计划;干净的受管文件可自动刷新,有本地改动则进入人工审阅 |
|
|
21
21
|
| 项目级验证 | 仓库 `make` 目标和 `scripts/workflow/*` | 必须保留项目语义;SCALE 不猜业务路由、凭据和服务拓扑 |
|
|
22
22
|
|
|
23
23
|
这意味着工作流适配不是 Codex-only。Codex 可以帮助审阅和处理 `manual-review`,但常规路径应该是命令驱动。
|
|
@@ -40,13 +40,14 @@ scale init --interactive
|
|
|
40
40
|
```bash
|
|
41
41
|
scale init --governance-pack standard
|
|
42
42
|
scale init --governance-pack project-scaffold
|
|
43
|
+
scale init --governance-pack scale-engine-repo
|
|
43
44
|
scale init --governance-pack moe-workspace
|
|
44
45
|
scale init --governance-pack go-service-matrix
|
|
45
46
|
scale init --governance-pack node-library
|
|
46
47
|
scale init --governance-pack frontend-app
|
|
47
48
|
```
|
|
48
49
|
|
|
49
|
-
不确定时先用 `standard`。仓库形态明确时再用更具体的 pack
|
|
50
|
+
不确定时先用 `standard`。仓库形态明确时再用更具体的 pack。`scale-engine-repo` 是 `scale-engine` 仓库自身的自托管 pack,不是普通业务仓库默认选项。
|
|
50
51
|
|
|
51
52
|
## 更新已有工作流
|
|
52
53
|
|
|
@@ -59,6 +60,13 @@ scale upgrade apply --dir . --confirm
|
|
|
59
60
|
scale preflight --dir . --service all --preflight-profile quick
|
|
60
61
|
```
|
|
61
62
|
|
|
63
|
+
默认输出是中文。需要英文命令提示或英文 HTML 计划时加 `--lang en`:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
scale upgrade check --dir . --lang en
|
|
67
|
+
scale upgrade plan --dir . --html --lang en
|
|
68
|
+
```
|
|
69
|
+
|
|
62
70
|
如果仓库已有本地封装,优先使用本地命令,因为它们编码了项目默认值:
|
|
63
71
|
|
|
64
72
|
```bash
|
|
@@ -80,11 +88,27 @@ scale upgrade rollback --dir .
|
|
|
80
88
|
| --- | --- | --- |
|
|
81
89
|
| clean | 生成的工作流集合和 lock 文件一致 | 运行项目级验证 |
|
|
82
90
|
| missing | 生成文件缺失 | 通常可用 `apply --confirm` 恢复 |
|
|
83
|
-
|
|
|
91
|
+
| updates-available | SCALE 版本、governance pack 或受管文件存在可应用更新 | 审阅计划,确认安全后应用 |
|
|
84
92
|
| manual-review | 生成文件已有本地修改 | 检查 diff,不要自动覆盖 |
|
|
85
93
|
|
|
86
94
|
`manual-review` 是有意设计。SCALE 不应该抹掉本地项目知识、服务命令或 Agent 规则。
|
|
87
95
|
|
|
96
|
+
## 自动升级边界
|
|
97
|
+
|
|
98
|
+
`scale upgrade apply --confirm` 现在覆盖三类安全场景:
|
|
99
|
+
|
|
100
|
+
- 受管文件缺失:从当前 governance pack 恢复缺失文件。
|
|
101
|
+
- SCALE CLI 版本变化:刷新 `.scale/governance.lock.json`,让项目记录当前 CLI 版本。
|
|
102
|
+
- governance pack 版本变化:如果受管文件内容仍与 lock 哈希一致,自动刷新这些干净文件,让新模板、新门禁、新脚本和新文档入口落到旧项目。
|
|
103
|
+
|
|
104
|
+
下面场景不会自动覆盖:
|
|
105
|
+
|
|
106
|
+
- 文件相对 lock 已有本地改动。
|
|
107
|
+
- 缺少 `.scale/governance.lock.json`,无法判断哪些文件由 SCALE 管理。
|
|
108
|
+
- 第三方 skills、MCP、浏览器、桌面自动化或外部 CLI 需要新增、升级、执行安装脚本。
|
|
109
|
+
|
|
110
|
+
这些情况会进入 `manual-review`,由维护者或 Agent 先看计划和 diff,再决定合并、保留本地改动,或重新初始化。
|
|
111
|
+
|
|
88
112
|
## 项目级适配
|
|
89
113
|
|
|
90
114
|
生成文件更新后,再按真实仓库适配这些文件:
|
|
@@ -127,13 +151,13 @@ scale upgrade rollback --dir .
|
|
|
127
151
|
|
|
128
152
|
```makefile
|
|
129
153
|
workflow-upgrade-check:
|
|
130
|
-
scale upgrade check --dir .
|
|
154
|
+
scale upgrade check --dir . --lang zh
|
|
131
155
|
workflow-upgrade-plan:
|
|
132
|
-
scale upgrade plan --dir . --html
|
|
156
|
+
scale upgrade plan --dir . --html --lang zh
|
|
133
157
|
workflow-upgrade-apply:
|
|
134
|
-
scale upgrade apply --dir . --confirm
|
|
158
|
+
scale upgrade apply --dir . --confirm --lang zh
|
|
135
159
|
workflow-upgrade-rollback:
|
|
136
|
-
scale upgrade rollback --dir .
|
|
160
|
+
scale upgrade rollback --dir . --lang zh
|
|
137
161
|
workflow-upgrade-verify:
|
|
138
162
|
scale preflight --dir . --service all --preflight-profile quick
|
|
139
163
|
```
|
|
@@ -145,6 +169,6 @@ workflow-upgrade-verify:
|
|
|
145
169
|
- `scale --version` 输出预期版本。
|
|
146
170
|
- `scale upgrade check --dir .` 没有非预期 drift。
|
|
147
171
|
- 有变更时,`scale upgrade plan --dir . --html` 能生成可审阅计划。
|
|
148
|
-
- `scale upgrade apply --dir . --confirm`
|
|
172
|
+
- `scale upgrade apply --dir . --confirm` 只在审阅计划后使用;干净受管文件可自动刷新,本地改动必须人工审阅。
|
|
149
173
|
- 项目级验证通过,或记录清楚已知失败。
|
|
150
174
|
- `README.md`、`AGENTS.md`、`CLAUDE.md`、`docs/workflow/README.md` 指向同一组工作流命令。
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# SCALE Engine 仓库工作流
|
|
2
|
+
|
|
3
|
+
这里描述的是 `scale-engine` 仓库自身的工程化工作流,不是终端用户如何使用 `scale` CLI。
|
|
4
|
+
|
|
5
|
+
## 入口
|
|
6
|
+
|
|
7
|
+
- 新维护者先读 [GETTING_STARTED.md](../guides/GETTING_STARTED.md)
|
|
8
|
+
- 日常开发读 [DEVELOPMENT_WORKFLOW.md](../guides/DEVELOPMENT_WORKFLOW.md)
|
|
9
|
+
- 机器可读分支策略看 [../../.scale/workspace.json](../../.scale/workspace.json)
|
|
10
|
+
|
|
11
|
+
## 最小命令面
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
make preflight
|
|
15
|
+
make new-task NAME=workflow-adaptation LEVEL=M
|
|
16
|
+
make plan NAME=workflow-adaptation LEVEL=M
|
|
17
|
+
make explore FILES='AGENTS.md CLAUDE.md README.md package.json' MSG='main contradiction'
|
|
18
|
+
make gate-workflow
|
|
19
|
+
make gate-quality
|
|
20
|
+
make verify PROFILE=default
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
PowerShell:
|
|
24
|
+
|
|
25
|
+
```powershell
|
|
26
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 -Profile default
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 门禁说明
|
|
30
|
+
|
|
31
|
+
| Gate | 作用 |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| G1 | 探索是否记录到状态文件,且至少读了 3 个文件 |
|
|
34
|
+
| G2 | 计划是否包含边界、异常、回滚、现实校验 |
|
|
35
|
+
| G3 | `src/` 行为改动是否伴随测试改动 |
|
|
36
|
+
| G4 | workflow 脚本是否可解析 |
|
|
37
|
+
| G5 | `lint + typecheck + test + build` 是否通过 |
|
|
38
|
+
| G6 | 任务证据和 `git diff --check` 是否通过 |
|
|
39
|
+
| G7 | 安全面是否通过 |
|
|
40
|
+
| G8 | Markdown 与工作流文档是否符合基础卫生规则 |
|
|
41
|
+
|
|
42
|
+
## 分支策略
|
|
43
|
+
|
|
44
|
+
当前仓库采用 GitLab Flow 风格:
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
feature/fix/docs/chore/codex -> dev -> master
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
约束:
|
|
51
|
+
|
|
52
|
+
- `dev` 是集成分支。
|
|
53
|
+
- `master` 是生产基线。
|
|
54
|
+
- `release/*` 只在必须从生产基线隔离发版时使用。
|
|
55
|
+
- `hotfix/*` 用于生产紧急修复,并要求回流 `dev`。
|
|
56
|
+
|
|
57
|
+
## 升级入口
|
|
58
|
+
|
|
59
|
+
如果要把仓库工作流继续升级到更新的 `scale-engine` 版本,先跑:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
make bootstrap-scale
|
|
63
|
+
make workflow-upgrade-check
|
|
64
|
+
make workflow-upgrade-plan
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
先审计划,再决定是否 `make workflow-upgrade-apply`。
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Generated by scale-engine governance pack: node-library@2
|
|
2
|
+
# Edit policy: prefer editing the pack in scale-engine; local overrides should be documented.
|
|
3
|
+
|
|
4
|
+
# Node Library Workflow
|
|
5
|
+
|
|
6
|
+
This repository uses the latest SCALE repository workflow for Node/npm package delivery.
|
|
7
|
+
|
|
8
|
+
## Command Entry Points
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
bash scripts/preflight/all.sh
|
|
12
|
+
bash scripts/gates/all.sh --dry-run
|
|
13
|
+
bash scripts/workflow/new-task.sh
|
|
14
|
+
bash scripts/workflow/resume.sh
|
|
15
|
+
bash scripts/workflow/verify.sh --preflight-profile quick
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
PowerShell:
|
|
19
|
+
|
|
20
|
+
```powershell
|
|
21
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/preflight/all.ps1
|
|
22
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/gates/all.ps1 --dry-run
|
|
23
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/new-task.ps1
|
|
24
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/resume.ps1
|
|
25
|
+
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/workflow/verify.ps1 --preflight-profile quick
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Default Verification Matrix
|
|
29
|
+
|
|
30
|
+
- quick loop: `npm run build`, `npm run lint`, `npm test`
|
|
31
|
+
- release loop: add `npm run typecheck`, `git diff --check`, and `npm pack --dry-run`
|
|
32
|
+
- product smoke: enable a real probe in `.scale/product-smoke.json` instead of treating a health endpoint as completion proof
|
|
33
|
+
|
|
34
|
+
## Branch Policy
|
|
35
|
+
|
|
36
|
+
This repository follows a GitLab Flow variant:
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
feature/fix/docs/chore/codex -> dev -> master -> tag/publish
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Use short-lived branches for governed work. Direct governed commits on `dev`, `master`, or `main` are blocked by SCALE ship rules.
|
|
43
|
+
|
|
44
|
+
## Release Expectations
|
|
45
|
+
|
|
46
|
+
Before a package release or demo handoff:
|
|
47
|
+
|
|
48
|
+
1. Run `bash scripts/preflight/all.sh` or the PowerShell equivalent.
|
|
49
|
+
2. Run `scale preflight --preflight-profile full --json`.
|
|
50
|
+
3. Run `npm pack --dry-run`.
|
|
51
|
+
4. Run `git diff --check`.
|
|
52
|
+
5. Confirm runtime evidence and review artifacts for M/L/CRITICAL work.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# API Contract
|
|
2
|
+
|
|
3
|
+
## Endpoint Or Interface
|
|
4
|
+
|
|
5
|
+
TBD
|
|
6
|
+
|
|
7
|
+
## Request
|
|
8
|
+
|
|
9
|
+
TBD
|
|
10
|
+
|
|
11
|
+
## Response
|
|
12
|
+
|
|
13
|
+
TBD
|
|
14
|
+
|
|
15
|
+
## Errors
|
|
16
|
+
|
|
17
|
+
TBD
|
|
18
|
+
|
|
19
|
+
## Permission Rules
|
|
20
|
+
|
|
21
|
+
TBD
|
|
22
|
+
|
|
23
|
+
## Compatibility Notes
|
|
24
|
+
|
|
25
|
+
TBD
|
|
26
|
+
|
|
27
|
+
## Acceptance Criteria
|
|
28
|
+
|
|
29
|
+
- [ ] TBD
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Architecture Review
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
- Modules touched:
|
|
6
|
+
- Public contracts touched:
|
|
7
|
+
- Data flow touched:
|
|
8
|
+
|
|
9
|
+
## Boundary Checks
|
|
10
|
+
|
|
11
|
+
- [ ] API/controller layer does not bypass service/usecase layer
|
|
12
|
+
- [ ] Domain layer is not coupled to infrastructure details
|
|
13
|
+
- [ ] Repository/ORM usage follows project conventions
|
|
14
|
+
- [ ] Shared framework components are reused instead of duplicated
|
|
15
|
+
- [ ] New abstractions remove real complexity
|
|
16
|
+
|
|
17
|
+
## Risks
|
|
18
|
+
|
|
19
|
+
- TBD
|
|
20
|
+
|
|
21
|
+
## Decision
|
|
22
|
+
|
|
23
|
+
- Approved/changes required:
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
name: SCALE Preflight
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
push:
|
|
6
|
+
branches:
|
|
7
|
+
- main
|
|
8
|
+
- master
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
preflight:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
steps:
|
|
14
|
+
- name: Checkout
|
|
15
|
+
uses: actions/checkout@v4
|
|
16
|
+
|
|
17
|
+
- name: Setup Node.js
|
|
18
|
+
uses: actions/setup-node@v4
|
|
19
|
+
with:
|
|
20
|
+
node-version: '20'
|
|
21
|
+
|
|
22
|
+
- name: Install project dependencies when present
|
|
23
|
+
shell: bash
|
|
24
|
+
run: |
|
|
25
|
+
if [ -f package-lock.json ]; then
|
|
26
|
+
npm ci
|
|
27
|
+
elif [ -f package.json ]; then
|
|
28
|
+
npm install
|
|
29
|
+
fi
|
|
30
|
+
|
|
31
|
+
- name: Run SCALE preflight
|
|
32
|
+
run: npx @hongmaple0820/scale-engine@latest preflight --service all --preflight-profile ci
|