✨ 这是什么（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 有什么区别？

🔗 它和 DeepSeek Harness 是什么关系？

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

核心原则

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

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

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

📜 V0.3：Documentation & Evidence Factory（16 项能力）

V0.3 解决"Factory 如何证明它生产的软件真的被正确设计、实现、测试、审核并交付"。 核心纪律：禁止文档垃圾（所有文档来自真实数据）· 禁止伪造证据（VERIFIED 只能来自真实运行）· 必需需求 NOT_TESTED → 阻止发布。

试验 p-005：31 文档 Gate PASSED → 失败注入（缺文档/STALE→FAIL→修复→PASS）→ OAuth 需求变更（32 文档 STALE → 再生）→ Audit RELEASE → 交付包 74 文件。 📖 V0.3 交付报告 · 实施计划

🏗️ 架构总览（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["交付：可运行项目 + 全套产物 + 事件/指标证据"]

📖 更多设计细节见 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 文档）

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

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

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

🎮 工厂案例（Community Case）

SILENT DEPTH 深海猎手（p-004 · 2D 战术潜艇游戏）

由 Software Factory V0.3 全自主生产的真实游戏 —— 独立仓库：github.com/yanzhao77/silent-depth

• 28/28 需求 VERIFIED · 363/363 测试（确定性引擎 byte-identical 快照）· Audit RELEASE
• 36 条证据全部 AUDITED · 31 份 game-profile 文档 · 158 文件交付包
• 📖 案例研究 · 审计报告 · 证据链

🤖 Agent Team（角色 Agent）

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

• 动态调度：按需 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）→ 通过才进入下一阶段

配套机制（V0.2）：Run 状态机（12 状态，非法迁移拒绝）、事件词汇（RUN*/PHASE/TASK_/AGENT*/ARTIFACT/QUALITYGATE/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 官方文档为准；本仓库不擅自编造版本号。

📁 仓库结构

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
│   │   │                             #   V0.3: docs · evidence · traceability · review · audit · docgate · delivery
│   │   └── 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）

🗺️ Roadmap

📖 详见 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）

完整模型见 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