@hongmaple0820/scale-engine 0.18.0 → 0.19.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.18.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.18.0-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.15.1
+# SCALE Engine v0.18.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,33 @@ 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)。
+
+## 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 +278,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 +297,36 @@ 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
 ```
 
+## Unreleased
+
+- 新增 Runtime Evidence + Memory Fabric：`scale runtime start/end/record/doctor/final-check` 和 `scale memory pack/doctor/settle`。
+- `memory settle` 会把真实运行证据沉淀为本地学习候选，默认需要人审后才能进入长期知识库或工程规范。
+- 官方 demo 已加入 runtime evidence、memory settle 和 HTML artifact 的完整闭环 smoke 测试。
+- 修复绝对 `SCALE_DIR` 在 resource governance 和 engineering standards 中被错误拼到项目目录下的问题。
+- 发版前质量门槛见 [Release Readiness](docs/RELEASE_READINESS.md)，官方 demo 必须跑通完整闭环后再发版。
+
+## 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 +335,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 更新