---

✨ 这是什么（What is this?）

DeepSeek Software Factory 是一个运行在 DeepSeek Harness 上的 Agent Preset / Software Factory： 你只需要输入自然语言软件需求，Factory 自动完成从需求到交付的完整软件生产流水线——并且全程可观察、可控制、可恢复、可重规划。

Natural Language Requirement
        ↓
Requirement Analysis → Product Design → Architecture
        ↓
Task Planning → Agent Team → Implementation
        ↓
Testing → Security → Build → Deployment → Delivery
        ↓
（V0.2：以上全程运行在持久 Run 状态机上，任何时刻可 Pause / Resume / Stop / Retry / Replan / Intervene）

最终产物不是一个设计文档，而是一个真实运行的项目 —— 就像 projects/p-001/（V0.1）与 projects/p-003/（V0.2）里已交付、可运行、带完整证据链的 Todo SaaS。

❓ 它和普通 Coding Agent 有什么区别？

	普通 Coding Agent	DeepSeek Software Factory
输入	"帮我写个登录功能"	一段完整软件需求
产出	一段/一屏代码	一个可运行、可测试、可构建、可部署的项目 + 全套产物
流程	直接写代码	需求→产品→架构→任务→角色团队→实现→测试→安全→构建→部署→交付
验证	自述"完成了"	Evidence over claims：Gate 独立验证（pytest/build/安全审计/review）
状态	对话即一切	持久 Run 状态机（12 状态，非法迁移拒绝）+ Artifact-first 交接
变更	重新生成	需求影响分析 + 动态 Replan：只重跑受影响任务，保留已完成工作
故障	报错重来	失败分类 + 自动恢复：retry / remediation 任务 / 换人 / 上报（attempts ≤3）
可观测	聊天记录	Live Workflow / Dashboard / Metrics / Cost：工厂实时可见

🔗 它和 DeepSeek Harness 是什么关系？

• DeepSeek Harness / Cordis Runtime 是底座（Host Plane）：注册表、沙箱与审批栈、持久化、模型路由、子代理、workflow —— 本仓库零修改。
• 本仓库 提供 Agent Plane：software-factory 预设（Factory Manager persona + 14 个技能）+ V0.2 工厂运行时（scripts/runtime/）+ 模板 + 真实案例。
• 两者关系 = 运行时 × 工厂。安装预设后，DeepSeek Harness 的每个会话都能变成一座软件工厂。

核心原则

原则	含义
🧩 Artifact-first	阶段之间靠产物交接（requirements.md → … → release-notes.md），产物版本化、依赖可追踪
⚖️ Evidence over claims	任务完成与否由独立验证决定；执行者自述不算数
🔁 可恢复	Run 状态持久化（runs/run-<n>/run.json + 事件日志），重启后继续而非从头再来
🧑‍💻 人类可控	随时 Pause / Resume / Stop / Retry / Replan / Intervene / Approve / Reject
🔍 诚实纪律	无数据 → UNKNOWN；估算 → ESTIMATED；未实现 → NOT IMPLEMENTED；绝不虚构

---

🏭 V0.2：Autonomous Software Production Runtime（14 项能力）

V0.2 把 V0.1 的"一次性 Pipeline"升级为持久生产运行时。核心对象：Project → Run → Plan → Task → Attempt → Agent → Artifact(版本) → Event。

#	能力	说明
1	Factory Run Control	持久 Run 状态机（CREATED/PLANNING/READY/RUNNING/PAUSED/STOPPING/STOPPED/FAILED/RETRYING/REPLANNING/COMPLETED/CANCELLED），非法迁移拒绝
2	Live Workflow	factory status 终端控制中心：阶段 ✓◉○✗⚠、进度条、Agent 活动、事件时间线、Quality Gates
3	Agent Observability / Trace	追加式执行轨迹（禁 CoT，只记客观事实）+ AGENT_* 事件
4	Artifact Lineage	版本化产物（不可变快照 + sha256）+ 依赖图 + 生产者/验证者追踪
5	Requirement Impact Analysis	不可变需求修订 + 产物级影响分析（affected/preserved/added/removed + agents + HIGH/MEDIUM/LOW）
6	Dynamic Replanning	Plan v1/v2 不可变文档 + propose → 用户批准 → 取消受影响 / 保留已完成 / 新建任务 / 继续
7	Failure Recovery	11 类失败分类 + attempts 账本（≤3）+ 恢复决策（retry/remediation/switch-agent/abort/escalate）
8	Human Intervention	USER_INTERVENTION 事件（user/action/target/reason）+ approve/reject/skip
9	Factory Metrics	成功率/时长/重试率/恢复率/Agent 利用率/产物率/Gate 失败率/安全失败率（全部由持久状态计算）
10	Token / Cost Accounting	cost 账本（每 Run/每 Agent），诚实标注 measured / estimated / unknown
11	Factory Dashboard	终端 + 自包含 HTML（真实数据，XSS 安全，零网络依赖）
12	Factory Templates	7 模板注册表：react-fastapi-saas / nextjs-saas / flutter-app / python-ai-service / rag-application / ai-agent-application / cli-tool
13	Cost-aware Model Routing	复杂度/重要性/角色/预算 → provider/model/reason（策略可配置）
14	Multi-project Foundation	Factory → Projects → Runs 层级，项目隔离，工厂级汇总

📖 详细交付见 reports/V0.2_DELIVERY_REPORT.md · 基线审计 docs/V0.2_BASELINE.md

---

🏗️ 架构总览（Architecture）

flowchart TB
    subgraph Runtime["DeepSeek Harness / Cordis Runtime"]
        HOST["Host Plane<br/>tools · skills · subagents · workflow<br/>storageDomain · approval · jobs"]
        PRESET["Agent Plane<br/>software-factory preset<br/>persona(17 原则) + 14 skills + tools"]
    end

    FM["Factory Manager<br/>(一个 Agent)"]
    RUNTIME["V0.2 Factory Runtime<br/>scripts/factory（scripts/runtime/）<br/>Run 状态机 · 事件 · Artifact 图 · Impact · Replan<br/>Recovery · Metrics · Cost · Dashboard"]
    PROJ["持久化<br/>runs/run-N/run.json · events.jsonl<br/>artifacts/registry.json · plans/ · requirements/ · memory/"]

    subgraph Roles["角色 Agent（continuable 子代理，按需动态创建）"]
        PM["PM"]; ARCH["Architect"]; FE["Frontend"]; BE["Backend"]
        QA["QA"]; REV["Review"]; SEC["Security"]; DEVOPS["DevOps"]
    end

    GATES["Quality Gates<br/>requirement · architecture · api · test · security · build · deployment"]

    USER["用户：自然语言需求"] --> FM
    FM --> PRESET --> HOST
    FM --> RUNTIME --> PROJ
    FM --> Roles
    Roles --> GATES --> FM
    FM --> DELIVERY["交付：可运行项目 + 全套产物 + 事件/指标证据"]

层	说明
Host Plane	Harness 自带（注册表 / 沙箱审批栈 / 持久化 / 模型路由），零修改
Agent Plane	software-factory 预设：Factory Manager persona（17 条运行原则）+ 14 个技能
V0.2 Runtime	scripts/runtime/（ESM）：Run 状态机 / 事件词汇 / 任务账本 / Agent 轨迹 / Artifact 图 / 影响分析 / Replan / 恢复 / 指标 / Cost / Dashboard / 模板 / 路由
角色团队	8 个角色子代理：动态创建、并行、复用（send_message）、换人（失败阶梯）
项目层	每项目独立目录：Run 状态 + 任务 DAG + 契约 + 版本化 Artifact + workspace + 账本

📖 更多设计细节见 Architecture 与 SOFTWARE_FACTORY_ARCHITECTURE.md（18 条 ADR）。

---

🚀 快速开始（Quick Start）

1. 安装预设

git clone https://github.com/yanzhao77/deepseek_software.git
cd deepseek_software
./scripts/install-preset.sh        # 安装到 ~/.dsh/.agent-presets/software-factory

2. 启动工厂（Harness 会话）

1. 打开 DeepSeek Harness Web GUI，新建会话

2. 会话预设选择 「软件工厂模式」（software-factory）

3. 输入你的软件需求，例如：

   创建一个 React + FastAPI + PostgreSQL Todo SaaS，支持注册、登录、CRUD 和 Docker 部署。

3. 直接使用 V0.2 运行时（无需 GUI 会话）

export FACTORY_ROOT=$PWD/projects          # 工厂根（默认即为仓库 projects/）
node --test scripts/runtime/test/          # 运行运行时测试套件（77 用例）

./scripts/factory template-list            # 查看 7 个工厂模板
./scripts/factory template-init react-fastapi-saas p-100 "My SaaS"
./scripts/factory run-start p-100          # 创建 Run（CREATED→PLANNING）
./scripts/factory run-advance p-100 READY "plan v1 ready"
./scripts/factory run-advance p-100 RUNNING "production starts"
./scripts/factory status p-100             # Live Workflow 控制中心
./scripts/factory dashboard p-100 --out dashboard.html   # 自包含 HTML Dashboard

常用控制：run-pause / run-resume / run-stop / run-retry / run-replan / run-intervene 常用记录：phase-start/complete · task-create/complete/fail/retry · agent-start/complete · artifact-add/dep/validate · requirement-set · impact · replan-propose/approve · failure-record · recover · metrics · cost-record/report

---

🏆 生产试运行（Production Trials）

p-001（V0.1）：React + FastAPI + PostgreSQL + Docker —— DELIVERED

cd projects/p-001/workspace
cp .env.example .env            # 替换 SECRET_KEY / POSTGRES_PASSWORD
docker compose up -d --build
# web:  http://localhost:8080
# api:  http://localhost:8000   （/docs 自动 OpenAPI 文档）

验证项	结果
测试	🟢 pytest 63 passed（QA 39 + 回归 9 + FR-6 15）
代码 Review	🟢 request-changes（15 项）→ 修复 8/8 → approve
安全审计	🟢 25 项检查 PASS（0 高/中危）
生产冒烟	🟢 全链路 + 数据持久化（db 重启验证）

p-003（V0.2）：Todo SaaS + OAuth 需求变更 + 失败恢复 —— DELIVERED

完整走完规格书 §35 场景：START → PAUSE → RESUME → … → REPLAN → RECOVER → DELIVERED

环节	真实证据
Run 状态机	CREATED→PLANNING→READY→RUNNING→…→COMPLETED（全部事件落盘）
需求变更注入	「把登录方式改成 OAuth」→ impact HIGH：affected {api-spec, backend-auth, frontend-login, authentication-tests}，preserved {database, deployment, todos 模块}（与规格书示例一致）
动态 Replan	Plan v1 → Plan v2（用户批准）→ 受影响任务取消、已完成工作保留、新建 OAuth 任务
失败注入	pytest 3 failed / 12 passed（OAuth 端点缺失）→ TEST_FAILURE 分类 → remediation 任务 → 实现 → 15/15 passed
质量门禁	requirement → architecture → api → test → security → build → deployment 全 PASS
Production Smoke	🟢 真实 HTTP：health / register 201 / login 401+200 / oauth 200 / todos CRUD / unauth 401
指标	Success 100% · Recovery 100% · 1 Replan · 3 Interventions · Cost $1.70（ESTIMATED，22 calls / 2.99M in / 0.81M out）

被生产的软件：projects/p-003/workspace/（FastAPI + React + Docker 配置，pytest 15）· 证据：projects/p-003/ + V0.2_PHASE10_PRODUCTION_TRIAL.md + V0.2_TRIAL_DASHBOARD.html

---

🤖 Agent Team（角色 Agent）

Factory Manager 按项目需要动态创建角色子代理（continuable 子代理：持久会话、可复用、可打断）：

角色	触发时机	主要产出
PM	需求批准后	product-spec.md
Architect	需求稳定后	architecture.md / api-spec.yaml / database-schema.sql
Backend	实现阶段	workspace/backend/**（FastAPI）
Frontend	实现阶段	workspace/frontend/**（React）
QA	后端就绪后	tests/**（pytest）
Review	实现+测试后	review-report.md（verdict）
Security	发布阶段	security-report.md
DevOps	发布阶段	Dockerfile / compose / build-report

• 动态调度：按需 spawn——纯 Web 项目不建 Mobile，纯 CRUD 不建 AI Engineer
• 并行：backend ∥ frontend、qa ∥ review 同轮并发
• 复用：同角色连续任务 send_message 复用同一会话（保留角色记忆）
• 换人：失败阶梯的 Switch Agent 步骤（全新 spawn）
• 契约注入：每次委派注入 role/mission/input/output/constraints/qualityCriteria/failurePolicy（见 contracts/<role>.yaml）
• V0.2 轨迹：每个角色的工作写入 agent-start/complete/fail 轨迹（目标/输入引用/工具摘要/产物/验证/结果/耗时——不含模型内部推理）

📖 详见 Agent Roles

---

🏭 生产流水线（Production Pipeline）

一条需求如何变成可运行软件：

Requirement → Clarification → Product Design → Architecture
  → Implementation → Integration → Testing → Security Audit
  → Build → Deployment → Delivery

每个阶段：输入产物 → 角色 Agent → 输出产物 → 独立验证（Gate）→ 通过才进入下一阶段

Phase	目标	状态
0 Discovery	运行时能力盘点（RUNTIME_CAPABILITY_MAP.md）	✅
1 Factory Preset	Factory Manager 预设 + 技能 + 模板	✅
2 Production Workflow	第一个完整闭环	✅
3 Agent Team	动态角色调度	✅
4 Quality Gate	自动验证 + 失败回退	✅
5 Human Intervention	暂停/恢复/审批/修改	✅
6 Requirement Change	影响分析 + 增量执行	✅
7 Production Trial	真实软件交付（p-001）	✅ DELIVERED
V0.2-1..9	Run Control / 事件+可观测 / Artifact 图 / 影响分析 / Replan / 恢复 / 指标+Cost / Dashboard / 模板+路由+多项目	✅ 77 测试
V0.2-10	Production Trial（p-003，OAuth 变更 + 失败恢复）	✅ DELIVERED

配套机制（V0.2）：Run 状态机（12 状态，非法迁移拒绝）、事件词汇（RUN_/PHASE_/TASK_/AGENT_/ARTIFACT_/QUALITY_GATE_/REPLAN_*/USER_INTERVENTION）、失败分类 11 类 + attempts ≤3、影响分析（产物图 + 任务 DAG）、Plan 版本化 + 审批流、Cost 诚实记账。

📖 详见 Production Pipeline · Quality Gates · Requirement Change · Human in the Loop

---

📦 安装（Installation）

# 1. 克隆仓库
git clone https://github.com/yanzhao77/deepseek_software.git
cd deepseek_software

# 2. 安装 software-factory 预设到 DSH 用户预设根（幂等）
./scripts/install-preset.sh
#    目标已存在时提示退出；强制覆盖：
./scripts/install-preset.sh --force

# 3. 验证
ls ~/.dsh/.agent-presets/software-factory/    # 应看到 agent.cordis.yml / preset.yml / skills/
node --test scripts/runtime/test/             # V0.2 运行时测试（77 用例）

安装后，DeepSeek Harness 新会话的预设列表会出现 「软件工厂模式」（software-factory）。

📖 完整说明（组成/卸载/更新/故障排查）：docs/wiki/AgentPreset.md

✅ 环境要求（Requirements）

依赖	用途	说明
DeepSeek Harness	运行时底座	预设挂载/会话运行环境；当前验证版本 0.1.0-rc.7 / Cordis / Node 22
Node.js ≥ 22	Harness 运行时 + V0.2 运行时（node --test）	scripts/runtime/ 使用 node:test 与 ESM
Git	仓库克隆、workspace 独立仓库	安装与工厂运行均需要
Python 3.9+ / Docker	生产试运行（p-001/p-003 冒烟/部署）	运行被生产项目时需要

⚠️ 不以本仓库为准的版本要求以 DeepSeek Harness 官方文档为准；本仓库不擅自编造版本号。

---

📁 仓库结构

deepseek_software/
├── agent-presets/software-factory/   # Factory Manager 预设源（persona 17 原则 + 14 技能）
├── projects/
│   ├── p-001/                        # V0.1 工厂项目（已 DELIVERED，Todo SaaS）
│   ├── p-002/                        # 工厂项目（Tank Battle）
│   └── p-003/                        # V0.2 试验项目（已 DELIVERED，OAuth 变更 + 失败恢复）
│       ├── project.json              #   V0.1 兼容投影（status/runStatus/events[]）
│       ├── runs/run-001/             #   权威 Run 状态 + 事件 + attempts
│       ├── artifacts/                #   版本化产物 + registry.json（依赖图）
│       ├── plans/ requirements/      #   Plan v1/v2 · 需求修订
│       ├── memory/                   #   failures / interventions / cost / traces / changes
│       └── workspace/                #   被生产的 Todo SaaS（backend + web + deploy）
├── scripts/
│   ├── factory                       # V0.2 工厂 CLI 包装器
│   ├── runtime/                      # V0.2 运行时（ESM 模块 + cli.js）
│   │   ├── lib/                      #   run-state-machine · store · events · tasks · trace
│   │   │                             #   observability · artifacts · impact · plans · failures
│   │   │                             #   metrics · cost · dashboard · templates · router
│   │   └── test/                     #   77 个 node --test 用例
│   ├── gates/                        # V0.1：test / build / security gate
│   ├── impact.js                     # V0.1：需求变更影响分析（DAG 闭包）
│   └── pipeline-check.sh             # V0.1：人类干预调度闸
├── templates/
│   ├── artifacts/                    # 15 个 Artifact 模板
│   ├── deployment/ project-skeleton/ # 部署模板 + 项目骨架
│   └── factory-templates/            # V0.2：7 个工厂模板注册表
├── docs/wiki/                        # 📚 项目 Wiki（13 页）
├── reports/                          # V0.1 阶段报告 + V0.2 阶段报告（PHASE1/2/3-9/10/DELIVERY）
├── RUNTIME_CAPABILITY_MAP.md         # Phase 0：运行时能力实测盘点
├── SOFTWARE_FACTORY_ARCHITECTURE.md  # 架构设计（18 条 ADR）
└── FACTORY_IMPLEMENTATION_PLAN.md    # 实施计划（Phase 0–7）

---

📚 文档（Documentation）

入口	内容
🏠 Wiki Home	项目说明总入口
Architecture	系统架构与两平面设计
Agent Preset	预设安装 / 使用 / 组成 / 卸载 / 故障排查
Production Pipeline	生产流水线（Phase 0–7 + V0.2）
Agent Roles	角色团队与调度机制
Quality Gates	质量门槛与失败回退
Requirement Change	需求变更引擎
Human in the Loop	人类干预机制
Security Model	安全边界
FAQ	常见问题
Roadmap	路线图与扩展点
V0.2 基线审计	V0.1 → V0.2 缺口与复用清单
V0.2 交付报告	V0.2 全量交付记录（14 能力 → 实现 → 测试 → 生产验证）
V0.2 试验报告	p-003 生产试运行（OAuth Replan + 失败恢复）
社区发布指南	GitHub Topics / 社区发现
贡献指南	如何参与开发
安全上报	安全模型与漏洞上报
V0.1 完成报告	V0.1 全量交付记录

---

🗺️ Roadmap

版本	内容	状态
V0.1	Factory Manager 预设 · 动态角色团队 · Artifact-first · Quality Gates · Human-in-the-loop · 需求变更引擎 · 生产试运行（p-001 DELIVERED）	✅ 已完成
V0.2	Factory Run Control 状态机 · Live Workflow · Agent Trace · Artifact Lineage · 需求影响分析 · 动态 Replan · 失败恢复（11 类分类） · Factory Metrics · Cost 记账 · Dashboard · 7 模板 · Model Router · 多项目（p-003 DELIVERED）	✅ 已完成
V0.3	多用户 · 组织/团队 · 云端部署 · Marketplace 集成 · 浏览器内实时 Dashboard（动态插件）	🧭 规划中

📖 详见 docs/wiki/Roadmap.md

---

⚠️ 约束与边界（Limitations，诚实清单）

• 不修改 DeepSeek Harness Core 与官方 shipped preset（standard/code/minimal/cordis 原样）
• 能力全部通过：用户预设 + 仓库内运行时（scripts/runtime/）+ 文件/脚本
• Cost 为 ESTIMATED（provider 未暴露 token 计量时用文档化费率 rates.json 推导并标注）；无数据时如实报 UNKNOWN，绝不虚构
• p-003 OAuth 为 mock provider（契约完整，生产替换点已文档化）—— 如实标注
• p-001/p-002（V0.1 项目无 Run 对象） 在工厂统计中 runs=0 —— 如实反映
• Dashboard 为终端 + 自包含 HTML（无浏览器内实时推送；动态 Client 插件路径需 approval，记 V0.3）
• 已知低危遗留（见 Security Model）：登录限流、时序侧信道、localStorage token、nginx TLS
• 仓库为中文文档为主；欢迎英文文档贡献（见 CONTRIBUTING.md）

🔒 安全（Security）

面	策略
命令执行	bash 走沙箱；破坏性命令触发审批/拒绝
文件访问	fs-sandbox 限定工作区；越界一次性升级需审批
Secrets	凭据只在 credentials 服务；SECRET_KEY 必填无默认；.env 永不进 git
子代理	approval policy 固定 never；越权/危险操作在子代理内确定性失败
依赖	版本锁定（requirements.txt / package-lock.json）；安全审计 Gate
Dashboard	产物 HTML 全字段转义（XSS 安全），零外部网络依赖

完整模型见 Security Model；漏洞上报见 SECURITY.md。

---

🤝 贡献（Contributing）

欢迎参与！优先方向：

• Agent Preset / Plugin Composition（不修改 Harness Core）
• V0.2 Runtime 扩展：新事件类型、新恢复策略、新模板、路由策略调优、Dashboard 渲染
• Skills 扩展（新角色/新技能）
• Tools / Workflow / Scripts（Gate、调度、影响分析）
• 文档与翻译（英文文档、Wiki）
• 社区案例（用 Factory 生产新项目并提交）

📖 详见 CONTRIBUTING.md

🌐 社区（Community）

• GitHub Topics：dsh-plugin · deepseek-harness · software-factory · agent-preset 等（见 docs/COMMUNITY_RELEASE.md）
• DeepSeek Harness Discussions：Show and tell 发布你的 Factory 成果
• DSH plugin ecosystem：作为 Agent Preset 参与社区生态
• 本仓库是 Community Project：未被任何官方 Marketplace 收录，也不声称任何官方认证/推荐

---

📜 许可证（License）

Apache-2.0