@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.
Files changed (155) hide show
  1. package/LICENSE +15 -15
  2. package/README.en.md +336 -304
  3. package/README.md +500 -475
  4. package/dist/adapters/AiderAdapter.js +52 -52
  5. package/dist/adapters/AntigravityAdapter.d.ts +4 -0
  6. package/dist/adapters/AntigravityAdapter.js +21 -0
  7. package/dist/adapters/AntigravityAdapter.js.map +1 -0
  8. package/dist/adapters/ClaudeCodeAdapter.d.ts +4 -1
  9. package/dist/adapters/ClaudeCodeAdapter.js +34 -34
  10. package/dist/adapters/ClaudeCodeAdapter.js.map +1 -1
  11. package/dist/adapters/ClineAdapter.d.ts +4 -0
  12. package/dist/adapters/ClineAdapter.js +20 -0
  13. package/dist/adapters/ClineAdapter.js.map +1 -0
  14. package/dist/adapters/CodexAdapter.js +28 -28
  15. package/dist/adapters/CursorAdapter.js +26 -26
  16. package/dist/adapters/DeepSeekTuiAdapter.js +97 -97
  17. package/dist/adapters/DoubaoAdapter.js +33 -33
  18. package/dist/adapters/GeminiAdapter.js +26 -26
  19. package/dist/adapters/GenericProjectAgentAdapter.d.ts +29 -0
  20. package/dist/adapters/GenericProjectAgentAdapter.js +204 -0
  21. package/dist/adapters/GenericProjectAgentAdapter.js.map +1 -0
  22. package/dist/adapters/HermesAdapter.js +26 -26
  23. package/dist/adapters/JCodeAdapter.d.ts +4 -0
  24. package/dist/adapters/JCodeAdapter.js +19 -0
  25. package/dist/adapters/JCodeAdapter.js.map +1 -0
  26. package/dist/adapters/KiloCodeAdapter.d.ts +4 -0
  27. package/dist/adapters/KiloCodeAdapter.js +20 -0
  28. package/dist/adapters/KiloCodeAdapter.js.map +1 -0
  29. package/dist/adapters/KimiAdapter.js +32 -32
  30. package/dist/adapters/KiroAdapter.js +26 -26
  31. package/dist/adapters/OpenClawAdapter.js +26 -26
  32. package/dist/adapters/OpenCodeAdapter.js +26 -26
  33. package/dist/adapters/QCoderAdapter.js +26 -26
  34. package/dist/adapters/QoderAdapter.d.ts +4 -0
  35. package/dist/adapters/QoderAdapter.js +21 -0
  36. package/dist/adapters/QoderAdapter.js.map +1 -0
  37. package/dist/adapters/TraeAdapter.js +26 -26
  38. package/dist/adapters/VSCAdapter.js +26 -26
  39. package/dist/adapters/WindsurfAdapter.js +32 -32
  40. package/dist/adapters/WorkBuddyAdapter.js +26 -26
  41. package/dist/adapters/index.d.ts +5 -0
  42. package/dist/adapters/index.js +15 -0
  43. package/dist/adapters/index.js.map +1 -1
  44. package/dist/api/cli.js +226 -48
  45. package/dist/api/cli.js.map +1 -1
  46. package/dist/api/doctor.js +10 -3
  47. package/dist/api/doctor.js.map +1 -1
  48. package/dist/api/quickstart.js +7 -1
  49. package/dist/api/quickstart.js.map +1 -1
  50. package/dist/artifact/sqliteStore.js +89 -89
  51. package/dist/artifact/types.d.ts +1 -1
  52. package/dist/cli/phaseCommands.js +45 -45
  53. package/dist/context/AntiPatternRegistry.js +20 -20
  54. package/dist/context/ContextBuilder.js +155 -155
  55. package/dist/evolution/EvolutionEngine.js +31 -31
  56. package/dist/evolution/EvolutionEvaluator.d.ts +2 -0
  57. package/dist/evolution/EvolutionEvaluator.js +7 -1
  58. package/dist/evolution/EvolutionEvaluator.js.map +1 -1
  59. package/dist/fsm/FSMAgentBridge.js +11 -11
  60. package/dist/hooks/HookGeneratorEnhanced.js +218 -218
  61. package/dist/index.d.ts +1 -1
  62. package/dist/index.js +2 -2
  63. package/dist/index.js.map +1 -1
  64. package/dist/knowledge/SQLiteKnowledgeBase.js +28 -28
  65. package/dist/memory/MemoryBrain.d.ts +1 -0
  66. package/dist/memory/MemoryBrain.js +55 -52
  67. package/dist/memory/MemoryBrain.js.map +1 -1
  68. package/dist/memory/MemoryFabric.d.ts +13 -1
  69. package/dist/memory/MemoryFabric.js +35 -0
  70. package/dist/memory/MemoryFabric.js.map +1 -1
  71. package/dist/memory/MemoryProviders.d.ts +111 -0
  72. package/dist/memory/MemoryProviders.js +385 -0
  73. package/dist/memory/MemoryProviders.js.map +1 -0
  74. package/dist/memory/index.d.ts +1 -0
  75. package/dist/memory/index.js +1 -0
  76. package/dist/memory/index.js.map +1 -1
  77. package/dist/output/GovernanceDashboard.js +44 -44
  78. package/dist/output/HTMLArtifactLayer.js +31 -31
  79. package/dist/prompts/VibeTemplateGallery.js +121 -121
  80. package/dist/skills/SkillDiscovery.js +12 -1
  81. package/dist/skills/SkillDiscovery.js.map +1 -1
  82. package/dist/skills/SkillRadar.js +20 -0
  83. package/dist/skills/SkillRadar.js.map +1 -1
  84. package/dist/skills/SkillRepository.d.ts +9 -1
  85. package/dist/skills/SkillRepository.js +70 -0
  86. package/dist/skills/SkillRepository.js.map +1 -1
  87. package/dist/skills/routing/SkillPlanner.js +40 -40
  88. package/dist/workflow/EngineeringStandards.js +62 -62
  89. package/dist/workflow/GovernanceTemplatePacks.d.ts +1 -1
  90. package/dist/workflow/GovernanceTemplatePacks.js +1990 -162
  91. package/dist/workflow/GovernanceTemplatePacks.js.map +1 -1
  92. package/dist/workflow/GovernanceTemplates.d.ts +2 -0
  93. package/dist/workflow/GovernanceTemplates.js +1012 -1001
  94. package/dist/workflow/GovernanceTemplates.js.map +1 -1
  95. package/dist/workflow/ResourceGovernance.js +16 -16
  96. package/dist/workflow/TaskArtifactScaffolder.js +10 -10
  97. package/dist/workflow/UpgradeManager.d.ts +3 -2
  98. package/dist/workflow/UpgradeManager.js +134 -49
  99. package/dist/workflow/UpgradeManager.js.map +1 -1
  100. package/dist/workflow/WorkspaceTopology.js +18 -15
  101. package/dist/workflow/WorkspaceTopology.js.map +1 -1
  102. package/docs/CODE_INTELLIGENCE.md +138 -138
  103. package/docs/CONTEXT_BUDGET.md +81 -81
  104. package/docs/EXTERNAL_REFERENCES.md +63 -0
  105. package/docs/GITLAB_FLOW.md +125 -125
  106. package/docs/GOVERNANCE_DASHBOARD.md +64 -64
  107. package/docs/MEMORY_BRAIN.md +104 -104
  108. package/docs/MEMORY_FABRIC.md +134 -107
  109. package/docs/README.md +79 -68
  110. package/docs/RUNTIME_EVIDENCE.md +101 -101
  111. package/docs/SKILL-REPOSITORY.md +57 -0
  112. package/docs/SKILL_RADAR.md +122 -115
  113. package/docs/THIRD_PARTY_SKILLS.md +57 -0
  114. package/docs/WORKFLOW_EVAL.md +151 -151
  115. package/docs/guides/DEVELOPMENT_WORKFLOW.md +80 -0
  116. package/docs/guides/GETTING_STARTED.md +50 -0
  117. package/docs/start/README.md +78 -72
  118. package/docs/start/agent-governance-demo.md +107 -107
  119. package/docs/start/quickstart.md +137 -127
  120. package/docs/start/workflow-upgrade.md +32 -8
  121. package/docs/workflow/README.md +67 -0
  122. package/docs/workflow/node-library.md +52 -0
  123. package/docs/workflow/templates/api-contract.md +29 -0
  124. package/docs/workflow/templates/architecture-review.md +23 -0
  125. package/docs/workflow/templates/db-change-plan.md +20 -0
  126. package/docs/workflow/templates/docs-impact.md +17 -0
  127. package/docs/workflow/templates/e2e-plan.md +20 -0
  128. package/docs/workflow/templates/explore.md +16 -0
  129. package/docs/workflow/templates/github-actions-scale-preflight.yml +32 -0
  130. package/docs/workflow/templates/mini-prd.md +16 -0
  131. package/docs/workflow/templates/plan.md +37 -0
  132. package/docs/workflow/templates/pre-push-scale-preflight.sh +8 -0
  133. package/docs/workflow/templates/product-smoke.md +61 -0
  134. package/docs/workflow/templates/reality-check.md +28 -0
  135. package/docs/workflow/templates/resource-cleanup.md +17 -0
  136. package/docs/workflow/templates/resource-impact.md +25 -0
  137. package/docs/workflow/templates/review.md +12 -0
  138. package/docs/workflow/templates/runtime.md +23 -0
  139. package/docs/workflow/templates/security-review.md +26 -0
  140. package/docs/workflow/templates/skill-evidence.md +33 -0
  141. package/docs/workflow/templates/skill-plan.md +39 -0
  142. package/docs/workflow/templates/spec.md +17 -0
  143. package/docs/workflow/templates/standards-impact.md +28 -0
  144. package/docs/workflow/templates/summary.md +16 -0
  145. package/docs/workflow/templates/tasks.md +8 -0
  146. package/docs/workflow/templates/ui-spec.md +29 -0
  147. package/docs/workflow/templates/verification.md +20 -0
  148. package/docs/workflow/templates/visual-review.md +20 -0
  149. package/examples/demo-projects/agent-governance-demo/CONTEXT.md +14 -14
  150. package/examples/demo-projects/agent-governance-demo/README.md +48 -48
  151. package/examples/demo-projects/agent-governance-demo/docs/CONTEXT-MAP.md +14 -14
  152. package/examples/demo-projects/agent-governance-demo/package.json +22 -21
  153. package/examples/demo-projects/agent-governance-demo/src/oauth-state.ts +39 -39
  154. package/examples/demo-projects/agent-governance-demo/tests/oauth-state.test.ts +52 -52
  155. package/package.json +88 -75
@@ -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
- 继续阅读 [官方 Demo Walkthrough](agent-governance-demo.md),看一个真实任务如何从需求到验证证据。
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` | 先安全检查和生成计划,只有 `--confirm` 才应用 |
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
- | outdated | SCALE 有更新的生成模板 | 审阅计划,确认安全后应用 |
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,20 @@
1
+ # DB Change Plan
2
+
3
+ ## Schema Or Data Change
4
+
5
+ TBD
6
+
7
+ ## Backward Compatibility
8
+
9
+ TBD
10
+
11
+ ## Migration Steps
12
+
13
+ TBD
14
+
15
+ ## Rollback Plan
16
+
17
+ TBD
18
+
19
+ ## Verification
20
+ TBD
@@ -0,0 +1,17 @@
1
+ # Docs Impact
2
+
3
+ ## Code Changes Requiring Docs
4
+
5
+ - TBD
6
+
7
+ ## Documentation Updated
8
+
9
+ - TBD
10
+
11
+ ## No-Docs-Needed Rationale
12
+
13
+ TBD
14
+
15
+ ## Links Checked
16
+
17
+ - TBD
@@ -0,0 +1,20 @@
1
+ # E2E Plan
2
+
3
+ ## User Paths
4
+
5
+ TBD
6
+
7
+ ## Browser Coverage
8
+
9
+ TBD
10
+
11
+ ## Test Data
12
+
13
+ TBD
14
+
15
+ ## Assertions
16
+
17
+ TBD
18
+
19
+ ## Evidence
20
+ TBD
@@ -0,0 +1,16 @@
1
+ # Explore - {{TASK_ID}}
2
+
3
+ Date: {{DATE}}
4
+ Level: {{LEVEL}}
5
+
6
+ ## Files Read
7
+
8
+ - TBD
9
+
10
+ ## Main Contradiction
11
+
12
+ - TBD
13
+
14
+ ## Constraints
15
+
16
+ - TBD
@@ -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
@@ -0,0 +1,16 @@
1
+ # Mini PRD - {{TASK_ID}}
2
+
3
+ Date: {{DATE}}
4
+ Level: {{LEVEL}}
5
+
6
+ ## Goal
7
+
8
+ - TBD
9
+
10
+ ## Non-Goals
11
+
12
+ - TBD
13
+
14
+ ## Acceptance Criteria
15
+
16
+ - TBD