@hongmaple0820/scale-engine 0.18.0 → 0.20.0

package/README.md

@@ -1,78 +1,85 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.15.1-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.20.0-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-16-blue?style=flat-square" alt="platforms" />
   <img src="https://img.shields.io/badge/agents-12-blue?style=flat-square" alt="agents" />
   <img src="https://img.shields.io/badge/workflows-10-green?style=flat-square" alt="workflows" />
   <img src="https://img.shields.io/badge/detectors-19-red?style=flat-square" alt="detectors" />
-  <img src="https://img.shields.io/badge/tests-822-passing-brightgreen?style=flat-square" alt="tests" />
-  <img src="https://img.shields.io/badge/npm-0.15.1-cb3837?style=flat-square&logo=npm" alt="npm" />
+  <img src="https://img.shields.io/badge/tests-verified-brightgreen?style=flat-square" alt="tests" />
+  <img src="https://img.shields.io/badge/npm-0.20.0-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.15.1
+# SCALE Engine v0.20.0
 
-SCALE Engine 是一个面向 AI 编码 Agent 的工程化工作流运行时。它把提示词里的工程纪律，下沉为状态机、质量门禁、持久化证据、确定性 review 记录和发布检查。
+SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探索、规划、实现、验证、评审、发版这些要求变成可执行的命令、门禁和证据文件，让人类可以看见 Agent 做了什么、跳过了什么、为什么不能交付。
 
 源码仓库：https://github.com/hongmaple0820/scale-engine
 国内镜像：https://gitee.com/hongmaple/scale-engine
 npm：https://www.npmjs.com/package/@hongmaple0820/scale-engine
 语言：[中文](README.md) | [English](README.en.md)
 
-## 为什么需要它
-
-提示词是建议，工程交付需要机制：
-
-- Agent 可以声称测试通过，SCALE 会保存真实验证证据。
-- Agent 可以跳过 review，SCALE 会在缺少 review 记录时阻断 `ship`。
-- Agent 可以误提交无关文件，SCALE 只暂存已通过 review 覆盖的文件。
-- Agent 可以丢失阶段状态，SCALE 会把 artifact 和 FSM 状态保存在 `.scale`。
-
-## 当前版本
-
-v0.15.1 聚焦生产级工程治理模板：
-
-- 支持 MOE / 非 MOE 工作区拓扑、子仓库变更阻断、临时 worktree 清理候选识别。
-- 增加资源资产治理，区分长期维护文档、版本化产物、任务证据、临时文件和禁止提交资产。
-- 增加工程规范扫描，覆盖日志噪音、敏感信息脱敏、安全输入、ORM/数据库、框架组件和测试验证。
-- 增强技能与工具编排，UI/UX、联网研究、浏览器 E2E、桌面自动化、外部 Agent CLI 都有路由和证据契约。
-- `scale init` / governance pack 会生成 service matrix、verification profile、artifact 模板、metrics、resource policy、engineering standards 和 tool orchestration 规则。
-
-历史 v0.11.1 新增四大优先级改进：
-
-### Phase Commands FSM 阻断
-- `canTransition` + `process.exit(1)` 确保 FSM guard 失败时阻塞流程，而非继续执行
-- define/plan/build/verify 各阶段添加明确的阻断提示
-
-### OWASP Top 10 检测器
-- 新增 `OWASPDetector` 覆盖 SQL 注入、XSS、路径遍历、SSRF、Auth Bypass、弱加密、CORS 错误配置、CSRF、文件上传、敏感数据泄露
-- 19 类安全检测模式，自动识别 regex 定义避免误报
-
-### Browser QA Capability
-- `BrowserQACapability` 封装 Playwright MCP 工具
-- 支持导航、点击、截图、console 检查、E2E 测试流程
-
-### L6 Evolution 自改进闭环
-- `LessonExtractor` 从会话 Defect 事件提取可复用教训
-- `SelfImproveEngine` 实现 `Defect → Lesson → Rule → Hook` 晋升流水线
-- 新增 CLI 命令：`scale evolution extract/improve/report/hooks`
-
----
-
-**完整阶段化交付链路**：
-
-- `define -> plan -> build -> verify -> review -> ship`
-- Spec、Plan、Task artifact 接入 FSM，guard 失败时阻断而非继续
-- 验证门禁证据持久化
-- 代码 review 记录持久化
-- 确定性 review scanner 会阻断空 `catch`、`@ts-ignore`、focused test、危险 shell/git 命令和缺 G7 证据的安全敏感变更
-- OWASP Top 10 安全检测器扩展安全覆盖
-- G7 内置安全扫描会记录可解释的文件/行号证据，默认阻断 CRITICAL，严格模式可阻断 HIGH
-- 可选严格 TDD evidence 门禁：`--tdd-evidence` 和 `--tdd-strict`
-- `ship --no-commit` 交付报告
-- `ship` 发布前强制验证 review evidence
-- 16 个平台适配器，12 个专业 Agent Profile
-- Browser QA Capability (Playwright MCP)
-- Evolution 自改进闭环
-- 本轮加固后，499 个 Vitest 测试通过
+## 它解决什么问题
+
+AI 编码真正难的不是“写代码”，而是持续稳定地遵守工程纪律：
+
+| 常见问题 | SCALE 的处理方式 |
+| --- | --- |
+| Agent 没验证却说“测试通过” | 通过 verification profile 和 evidence store 记录真实命令与结果 |
+| Agent 跳过需求澄清、设计、TDD 或 review | 通过 `scale context`、`scale diagnose`、`scale tdd`、`scale status` 生成下一步动作 |
+| Agent 误提交无关文件或跨仓库改错位置 | 通过 review-gated ship、MOE workspace 和子仓库 blocker 控制边界 |
+| 文档、报告、截图、临时脚本越堆越乱 | 通过 resource governance 区分长期维护、任务证据、临时产物和禁止提交资产 |
+| 日志噪音、敏感信息、ORM/框架乱用、安全风险无人兜底 | 通过 engineering standards 和 OWASP 扫描给出可追溯问题 |
+| Markdown 长报告没人读 | 通过 `scale artifact` 从 Markdown 源文件生成可追溯 HTML 报告 |
+
+## 3 分钟看到效果
+
+```bash
+npm install -g @hongmaple0820/scale-engine
+mkdir scale-demo && cd scale-demo
+scale init --governance-pack standard
+scale preflight --preflight-profile quick
+scale status
+```
+
+你会得到一套可提交到项目里的治理文件：
+
+- `.scale/verification.json`：服务矩阵和验证 profile
+- `.scale/skills.json`：skill 路由和证据要求
+- `.scale/tools.json`：CLI/MCP/browser/desktop 工具编排规则
+- `docs/workflow/templates/`：Mini-PRD、plan、verification、review、summary 模板
+- `docs/standards/`：工程规范、Git 协作、资源治理规则
+
+继续体验完整闭环：
+
+```bash
+scale context init --name "Scale Demo"
+scale context grill --task-id 2026-05-18-oauth-hardening --task "加固 OAuth callback"
+scale diagnose plan --task-id 2026-05-18-oauth-hardening --symptom "callback 在 state 过期时返回 500"
+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
+scale artifact render --task-id 2026-05-18-oauth-hardening --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
+scale artifact doctor --artifact-dir docs/worklog/tasks/2026-05-18-oauth-hardening
+```
+
+完整教程见 [3 分钟快速开始](docs/start/quickstart.md) 和 [官方 Demo Walkthrough](docs/start/agent-governance-demo.md)。
+
+## 适合谁
+
+- 正在用 Codex、Claude Code、Cursor、Gemini CLI、OpenCode、Aider 等 Agent 写真实项目的团队。
+- 有多服务、多仓库、MOE workspace、前后端分离、脚手架治理需求的团队。
+- 希望 Agent 主动使用 skills、MCP、CLI、浏览器、E2E、HTML 报告，但又需要安全边界和证据闭环的团队。
+- 经常遇到“AI 改得快，但难审、难验、难维护”的项目负责人。
+
+不适合只想要一个极简 prompt 文件、完全不需要门禁、不关心多人协作和长期维护的玩具项目。
+
+## 核心能力
+
+- Workflow Engine：`define -> plan -> build -> verify -> review -> ship` 的阶段化交付状态机。
+- GateSystem：build、lint、test、coverage、security、TDD、review、tool evidence 等门禁。
+- Governance Packs：`standard`、`project-scaffold`、`moe-workspace`、`resource-governance`、`go-service-matrix`、`node-library`、`frontend-app`。
+- Resource Governance：治理文档、图片、视频、报告、测试脚本、临时脚本、HTML artifact 和本地配置。
+- Skill and Tool Orchestration：把 UI/UX、联网研究、浏览器 E2E、Chrome DevTools MCP、桌面自动化、外部 Agent CLI 纳入流程。
+- Runtime Evidence：记录会话、命令、工具、浏览器、skill 和最终交付证据，阻断“没有证据却声称完成”。
+- Engineering Standards：扫描日志噪音、敏感信息、注入风险、ORM/数据库、框架边界、测试严谨性和部署风险。
+- HTML Artifacts：Markdown 仍是可维护源文件，HTML 用于评审、对比、状态报告和发版交接。
 
 ## 安装
 
@@ -83,6 +90,36 @@ scale --version
 
 需要 Node.js 20 或更高版本。
 
+## Governance Pack
+
+在已有项目中安装治理工作流：
+
+```bash
+scale init --governance-pack standard
+scale init --governance-pack project-scaffold
+scale init --governance-pack moe-workspace
+scale init --governance-pack resource-governance
+scale init --governance-pack go-service-matrix
+scale init --governance-pack node-library
+scale init --governance-pack frontend-app
+```
+
+当前支持的治理包：
+
+| Pack | 适用场景 |
+| --- | --- |
+| `standard` | 通用项目治理，包含任务 artifact、验证、指标、资源、规范和 skills policy |
+| `project-scaffold` | 可复现的工程化工作流脚手架和治理 demo 项目 |
+| `moe-workspace` | 父工作区 + 独立子仓库，适合 MOE/多仓协作 |
+| `resource-governance` | 文档、报告、截图、脚本、媒体、生成产物等资源生命周期治理 |
+| `go-service-matrix` | Go 后端服务矩阵，支持按服务 build/lint/test/security 验证 |
+| `node-library` | Node/TypeScript 包的开发、发布和验证治理 |
+| `frontend-app` | UI/UX、浏览器证据、响应式检查、E2E 和视觉评审治理 |
+
+如果不确定选哪个，先用 `standard`。场景明确时再使用更具体的 pack：
+
+更多命令和使用路径见 [入门文档索引](docs/start/README.md)。
+
 ## Vibe Templates（一键启动）
 
 内置高质量提示词模板，无需输入复杂指令：
@@ -139,6 +176,129 @@ scale verify <task-id> --tdd-strict --tdd-evidence .scale/tdd/<task-id>.json
 
 TDD evidence JSON 需要包含 `red`、`green`、`refactor`、`testFirst` 且值都为 `true`。
 
+## Memory Fabric
+
+Memory Fabric 会在长会话中把 runtime evidence、session events、knowledge recall 和 graph status 压缩成可预算的 context pack：
+
+```bash
+scale memory pack --task "Fix OAuth callback state lookup" --task-id <task-id> --session-id <session-id> --level M --budget 4000
+scale memory doctor --task "Review cross-module permission change" --level L --budget 3000
+scale memory settle --task "Fix OAuth callback state lookup" --task-id <task-id> --session-id <session-id> --level M
+```
+
+`memory settle` 会把已记录的运行证据沉淀为 `.scale/memory/learning-candidates/` 下的学习候选。候选默认需要人审，避免把一次会话里的临时判断直接污染长期知识库。
+
+详见 [Memory Fabric](docs/MEMORY_FABRIC.md)。
+
+## Context Budget 与 Progressive Governance
+
+Context Budget 会把 always-loaded、on-demand、evidence、archive、generated 上下文分开统计，避免 Agent 把所有规则、历史方案、报告和生成物一次性塞进提示词。
+
+```bash
+scale context budget --json
+scale context doctor --max-always 2500 --max-task 8000
+scale context pack --task "Review frontend route with browser evidence" --level L --budget 4000 --json
+```
+
+Progressive Governance 会根据任务文本和变更文件自动推荐 `minimal`、`standard`、`expanded` 或 `critical` 治理模式，并用 ROI 报告解释治理收益和开销：
+
+```bash
+scale governance mode --task "Change auth permissions" --files src/auth/user.ts --requested-mode minimal --json
+scale governance roi --task-id <task-id> --task "Review frontend route" --files src/routes/upload.tsx --json
+```
+
+详见 [Context Budget And Progressive Governance](docs/CONTEXT_BUDGET.md)。
+
+## Code Intelligence 与探索 ROI
+
+Code Intelligence 是 adapter-first 的代码理解层：优先消费外部 CodeGraph 或 Graphify 产物，缺失时明确降级到内部 source scan，不静默假装已经完成代码图谱分析。
+
+```bash
+scale codegraph init
+scale codegraph status --json
+scale codegraph query "UserService.create" --json
+scale codegraph impact --symbol UserService.create --json
+scale codegraph context --symbol UserService.create --budget 2000 --json
+scale codegraph roi --symbol UserService.create --json
+```
+
+它会输出 provider、fallback 状态、相关文件、confidence，以及 `fileReadsSaved` / `toolCallsSaved` 等探索收益指标。`scale governance roi` 也可以通过 `--symbol` 或 `--code-query` 把代码智能纳入治理 ROI。
+
+详见 [Code Intelligence](docs/CODE_INTELLIGENCE.md)。
+
+## Workflow Eval 与 Failure Replay
+
+Workflow Eval 用轻量套件衡量工作流是否真的减少返工、工具调用、token 消耗和人类纠偏。失败时会保留 Failure Replay，而不是只留下一个失败状态。
+
+```bash
+scale eval init
+scale eval run --suite workflow-baseline --json
+scale eval compare --baseline <run-id> --candidate <run-id> --json
+scale eval failures --since 30d --json
+scale eval promote-failure <failure-id>
+```
+
+默认产物写入 `.scale/evals/`，属于本地运行时证据。长期提交到 Git 的应是经过整理的报告、基准 fixture 或明确要沉淀的改进项。
+
+详见 [Workflow Eval Harness](docs/WORKFLOW_EVAL.md)。
+
+## Skill Radar
+
+Skill Radar chooses skills, MCP, browser automation, desktop automation, and external CLIs by task intent instead of relying on a static prompt list. It returns confidence, safety level, evidence requirements, and fallback behavior so agents can actively use tools without silently crossing safety boundaries.
+
+```bash
+scale skill radar --task "Design upload UI and run browser E2E checks" --files src/pages/upload.tsx
+scale skill radar --task "Automate WPS desktop workflow with CUA" --json
+scale skill doctor --supply-chain
+```
+
+Desktop CUA and external agent CLIs are blocked by default through Tool Policy until deliberately enabled. Third-party skills stay review-required until source, scripts, license, and pinned revision are checked.
+
+See [Skill Radar](docs/SKILL_RADAR.md).
+
+## Memory Brain
+
+Memory Brain stores long-term project knowledge separately from the short context pack. Runtime evidence and learning candidates enter as candidates first; active memory requires evidence paths, project scope, confidence, and explicit promotion.
+
+```bash
+scale memory ingest --from evidence --task-id <task-id>
+scale memory ingest --from failure --failure-id <failure-replay-id>
+scale memory query "OAuth callback state design"
+scale memory contradictions --json
+scale memory dream --json
+scale memory promote <candidate-id>
+```
+
+The point is not to remember everything. The point is to keep useful, reviewed project facts while reporting contradictions instead of silently overwriting them.
+
+See [Memory Brain](docs/MEMORY_BRAIN.md).
+
+## Governance Dashboard
+
+Governance Dashboard renders a local HTML health view from runtime evidence, Workflow Eval, Memory Brain, Resource Governance, and task HTML artifacts:
+
+```bash
+scale artifact dashboard
+scale artifact dashboard --task-id <task-id> --json
+```
+
+Default output is `.scale/reports/governance-dashboard.html`. Markdown and JSON remain the maintainable source of truth; the dashboard is a review surface for humans.
+
+See [Governance Dashboard](docs/GOVERNANCE_DASHBOARD.md).
+
+## Runtime Evidence
+
+M/L/CRITICAL 任务在最终交付前应留下运行时证据，避免 Agent 没有真实验证就声称完成：
+
+```bash
+scale runtime start --session-id <session-id> --task-id <task-id> --level M --agent codex
+scale runtime record --title "build" --kind command --status passed --command "npm run build" --exit-code 0 --summary "build passed"
+scale runtime final-check --task-id <task-id> --session-id <session-id> --level M
+scale runtime doctor --task-id <task-id> --session-id <session-id> --level M
+```
+
+证据写入 `.scale/events/sessions/` 和 `.scale/evidence/runtime/`，默认属于本地运行时产物，不应提交到 Git。详见 [Runtime Evidence](docs/RUNTIME_EVIDENCE.md)。
+
 ## Evolution 自改进闭环
 
 从会话缺陷中提取教训，晋升为规则和 Hook：
@@ -214,7 +374,7 @@ src/guardrails/                detector 与 gateway
 src/guardrails/OWASPDetector.ts OWASP Top 10 安全检测
 src/capabilities/BrowserQACapability.ts Playwright MCP 包装器
 src/evolution/                 Defect/Lesson/Rule/Hook 自进化层
-tests/                         Vitest 测试 (499 tests)
+tests/                         Vitest 测试套件
 ```
 
 ## 开发与验证
@@ -233,6 +393,38 @@ npx vitest run tests/workflow/phaseCli.test.ts
 npx vitest run tests/workflow/reviewAnalyzer.test.ts tests/workflow/reviewStore.test.ts tests/workflow/gateSystem.test.ts
 ```
 
+## v0.20.0 Updates
+
+- Added Context Budget and Progressive Governance so low-risk S tasks stay lightweight while auth, data, security, deployment, and cross-module changes escalate automatically.
+- Added Code Intelligence with adapter-first CodeGraph / Graphify support, explicit fallback, impact analysis, context recommendations, and exploration ROI.
+- Added Workflow Eval, Failure Replay, and improvement candidates with pass@k, fix iterations, tool-call counts, token estimates, and human-correction metrics.
+- Added Skill Radar for intent-based skills, MCP, browser, desktop automation, and external CLI recommendations with confidence, safety level, and evidence requirements.
+- Added Memory Brain for evidence-backed long-term memory candidates, contradiction detection, dream maintenance, explicit promotion, and failure replay ingestion.
+- Added Governance Dashboard to summarize runtime, eval, memory, resource, and HTML artifact evidence in a local HTML review surface.
+- Fixed new --dir-aware commands so relative .scale state resolves inside the target project instead of the caller workspace.
+
+## v0.18.0 更新
+
+- 新增受治理 HTML artifact：`scale artifact render/doctor/settle/open`。
+- Markdown 保持为可维护源文件；生成 HTML 作为可追溯任务证据。
+- governance pack 增加 output policy 和 HTML artifact 资源分类。
+- 增加 HTML 渲染、安全检查、settlement evidence 和模板生成测试。
+
+## v0.17.0 更新
+
+- 新增主动工作流命令门控：`scale context`、`scale diagnose`、`scale tdd`、`scale status`。
+- 增加 required next-action queue，减少 Agent 静默跳过上下文、调试、TDD 或验证步骤。
+
+## v0.16.0 更新
+
+- 新增受治理 skill repository、skill 推荐、安装安全检查、可视化 Vibe 模板和领导者角色预设。
+- 加强工具编排、资源治理和工程规范治理。
+
+## v0.15.1 更新
+
+- 新增 UI/UX、联网研究、浏览器自动化、桌面自动化和外部 Agent CLI 路由契约。
+- 为生成项目包增加资源治理和工程规范治理。
+
 ## v0.11.1 更新
 
 - Phase Commands FSM 阻断：`canTransition` + `process.exit(1)` 确保 guard 失败时阻塞
@@ -241,7 +433,7 @@ npx vitest run tests/workflow/reviewAnalyzer.test.ts tests/workflow/reviewStore.
 - L6 Evolution：`Defect → Lesson → Rule → Hook` 自改进闭环
 - Evolution CLI：`scale evolution extract/improve/report/hooks`
 - ReviewAnalyzer regex 修复：避免模式定义误报
-- 499 测试通过
+- Vitest 测试套件纳入发布验证
 
 ## v0.10.1 更新