esonx/dsh-project-j4agent

J4Agent

面向 DeepSeek Harness 的 Agent-native 软件研发全生命周期管理

不是给 Agent 用的 Jira。
而是一套围绕人类与 Coding Agent 实际协作方式设计的研发模型。

J4Agent 是 DeepSeek Harness 的轻量研发管理层。它将需求、实现工作、验证证据、版本状态、Artifact 和发布连接为共享项目事实，供人类与 Agent 以同一方式理解和使用。

这些情况是否似曾相识？

Coding Agent 很快。但当它真正进入研发流程后，另一组问题就会出现：

- 进度丢失 —— 一次长对话或上下文重置后，你和 Agent 都难以快速判断哪些已完成、哪些未完成、下一步应做什么。
- “已完成”却没有把握 —— Agent 说功能可用或测试全过，但你仍不得不亲自核验每一项。
- 任务漂移 —— 清晰的任务逐渐变成别的事情：旧方案重新浮现、假设未被检验、无关工作被带入范围。
- 监督成为瓶颈 —— 代码生成更快了，但更多时间花在确认状态、审查输出、校正方向，以及追问测试是否真的执行过。
- 流程规则容易被遗忘 —— 重要说明写在 CLAUDE.md、AGENTS.md 或 Prompt 中，但对话变长后，Agent 仍可能跳过某一步。
- 项目记忆变成文档堆积 —— 计划、交接记录、Memory 文件与 TODO 不断增加，却没有人能完全确定哪一版仍反映当前项目。

这些问题背后有一个更基础的问题：

当 Agent 说“完成”时，“完成”究竟意味着什么？

代码是否已写？测试是否真的运行过？当前实现是否仍是当时通过验证的那个实现？Feature 是否可以发布？

随着 Coding Agent 变得更快、更自主，生成代码正越来越不是主要瓶颈。让研发过程持续、可信、可理解，正在成为更难的问题。

这正是 J4Agent v0.2.0-alpha.1 要解决的问题。

J4Agent v0.2.0-alpha.1 —— 一次模型升级

v0.2.0-alpha.1 不是 J4Agent v0.1.x 的简单扩容。研发逻辑以一个不同的假设重新构建：

Agent 不应只是操作一个面向人类的任务跟踪器。研发模型本身应当能被人类与 Agent 共同理解、执行和验证。

新的 Agent-native 研发旅程是：

Requirement
↓
Feature
↓
Work
↓
Verification
↓
Release

每一阶段表达不同的研发事实：

- Requirement（需求） —— 用户实际想要什么，以及该意图在研发过程中如何演进。
- Feature（功能） —— 用于组织实现和验证的稳定能力或交付单元。
- Work（工作） —— 在项目上实际执行的研发活动。
- Verification（验证） —— 证明当前实现已经测试，并且对相关版本仍然有效的结构化证据。
- Release（发布） —— 被有意一起交付的、已经验证的 Features。

因此，v0.2.0-alpha.1 将 J4Agent 从 Jira 式 Work Item 模型转向 面向 Agent 的软件研发事实模型。

相比 v0.1.x 改变了什么？

| v0.1.x | v0.2.0-alpha.1 |
| --- | --- |
| 围绕 Work Item 组织 | 围绕研发旅程组织 |
| Jira 式事项类型居中 | Requirement / Feature / Work / Verification / Release 是彼此独立的领域事实 |
| Task 是首要单元 | Feature 是稳定的交付单元 |
| Requirement 大多像一个事项 | Requirement 是带有可追溯 Requirement Item 的、持续演进的用户目标 |
| Verification 是辅助项目数据 | Verification 是正式的 Feature Gate |
| 测试状态主要是记录的状态 | Verification 绑定到实际观察到的实现版本 |
| Agent 主要操作任务/项目数据 | Agent 可以沿完整研发旅程导航 |
| 流程高度依赖模型理解 | Policy、Analyze、Workflow Brief 和 Continuation 暴露当前状态与合法下一步 |
| 文档松散关联 | Artifact 形成渐进式研发上下文链路 |
| Task Graph 是主要组织中心 | Task Graph 是底层 Work 事实的一种投影 |

v0.2.0-alpha.1 是研发模型升级，而不只是一次功能发布。

为什么需要 Agent-native 研发管理？

传统事项跟踪器主要为人类协调人类而设计。Coding Agent 带来了不同的约束：

- 模型上下文是暂时的；
- 实现已经开始后，需求仍可能变化；
- 自然语言的“已完成”声明不是完成证明；
- 实现变化后，测试证据可能失效；
- 大型项目文档很有价值，但持续注入模型上下文代价高且容易出错；
- 写在 Prompt 中的流程仍依赖模型记得遵守它。

J4Agent 将 推理 与 项目事实 分离。

让模型负责推理，让 J4Agent 约束事实。

Agent 仍可自由理解需求、提出方案、编写代码、调查失败原因和解释取舍。J4Agent 维护围绕这些工作的结构化状态：正在构建什么、什么发生了变化、还剩什么、什么已经测试、哪个实现版本已经验证、什么被阻塞，以及当前合法的下一步是什么。

核心研发模型

1. Requirement —— 持续演进的用户目标

真实需求很少在第一次 Prompt 后保持不变。项目已经开始研发时，用户仍可能澄清细节、调整范围、拆分能力，或发现遗漏条件。

J4Agent 通过 Requirement Item 对其建模：

Requirement
├── Requirement Item A ──→ implementation Work
├── Requirement Item B ──→ implementation Work
└── Requirement Item C ──→ implementation Work

Requirement Item 可以保持 active、被新的解释替代，或在不再需要时移除。Requirement 被认为完成之前，其仍处于 active 的需求点必须能追溯到实际实现。

Requirement 有意区别于 Feature 或 Release：

- 完成一个 Feature，不代表用户的 Requirement 已结束；
- 发布一个 Release，不会自动结束 Requirement；
- 同一个 Requirement 可以跨多个 Feature 和 Release 持续演进。

Requirement 的关闭是人类决策。 Agent 可以分析当前 Requirement 是否看起来满足关闭条件，但不能代替用户决定产品目标已经完成。

2. Feature —— 稳定的交付单元

Feature 表示一项可被独立理解、实现、验证和发布的能力。每个 active Requirement 必须至少拥有一个 Feature。

Requirement 可以继续演进；Feature 则提供更稳定的单元，以便围绕它组织实现、验证和发布。

3. Work —— 实际发生了什么

Work 描述真实的研发活动，而不只是一张 TODO 清单。J4Agent 按 Work 是否改变生产事实加以区分。

Production Work（生产工作）

示例包括：

- 实现代码；
- Bug 修复；
- 依赖变更；
- 配置变更；
- 构建或 Pipeline 变更；
- Migration 与 Schema 变更；
- 其他发布关键的生产修改。

Production Work 按定义即为 release-critical。

Non-production Work（非生产工作）

示例包括：文档、调研、规划、图表，以及其他不改变生产行为的工作。

这一区分很重要，因为相关 Production Work 可能使之前的 Verification 失效。

4. Verification —— 关于当前实现的证明

Verification 不只是另一个状态字段。

一个 Feature 拥有持续存在的 Verification Gate。TestWork 隶属该 Verification，并覆盖相关的 Production Work。一次测试尝试记录以下结构化事实：

- 执行了哪个 TestWork；
- 所属的 Verification Cycle；
- 通过或失败的结果；
- 必填摘要；
- Evidence（证据）；
- Host 实际观察到的版本状态。

Verification Pass 要求当前且有效的 Evidence，以及结构化确认流程。

Verification 可能变为 stale

某个 Feature 今天可能通过全部测试。明天，生产代码、依赖、配置、Pipeline 或 Schema 可能发生变化；之前的结果可能不再证明新的实现。

相关 Production Change
↓
之前的 Verification
↓
stale
↓
需要重新验证

Verification 跟随实现事实。

5. Release —— 实际交付了什么

Release 是包含已验证 Features 的明确交付边界。

在一个 Release ready 前，J4Agent 可以评估：

- 纳入的 Features 是否拥有当前已通过的 Verification；
- release-critical Production Work 是否已完成；
- 相关版本状态是否稳定且已解析；
- 当前 Verification 是否仍与 Release candidate 兼容；
- 是否仍有未解决的生产或版本事实阻塞交付。

已经 released 的 Feature 后续发生维护修改时，应走新的 maintenance lineage，而不是悄悄改写历史交付记录。

Agent 指导：持续留在研发旅程中

仅仅给 Agent 提供项目管理 API 还不够。Agent 还需要理解自己在哪里、什么值得优先关注，以及无需在每次 Tool 调用时重建整个项目就能知道下一步可做什么。

J4Agent 从当前项目事实派生轻量指导：

持久化项目事实
↓
Agent 交互状态
┌────┴─────┐
↓          ↓
Workflow     Continuation
Brief

Workflow Brief

Workflow Brief 是紧凑的导航摘要，可暴露：

- 当前旅程状态；
- 当前关注点；
- 最高优先级的注意事项；
- 下一个有意义的步骤；
- 当项目事实可能需要更新时的同步提示。

它不会创建另一套事实源，而是由 J4Agent 其他位置使用的同一套持久事实和 Policy 派生。Agent 需要更多细节时，Brief 可以指向只读的 Context、Analyze 或 Help Surface，而不是把大段说明嵌进每一次响应。

Continuation

Continuation 回答的是另一个问题：

我现在实际可以做什么？

它暴露合法的下一步操作；若 J4Agent 已经知道继续所需的固定标识或版本，也会一并提供。

目标是减少猜测、无效 Tool 调用、过期版本、流程漂移与重复重建项目状态。

一个关键设计原则是：

流程不应依赖 Agent 记得遵守某一段文字。

Prompt 帮助 Agent 推理；项目事实与 Policy 定义实际的研发状态。

具备版本意识的研发

Verification 与 Release 都需要知道它们正在评估 哪个实现状态。J4Agent 支持两种 Revision Mode。

Local Mode

Local Mode 不依赖 Git。J4Agent 会观察有效项目文件的稳定 Workspace Snapshot，并以此 Revision Identity 执行 Verification 与 Release 检查。这让不使用 Git 的本地项目也能拥有完整研发旅程。

Git Mode

Git Mode 可以观察 Repository、Worktree、Branch、HEAD、dirty state 以及相关版本事实。

J4Agent 有意做到 Git-aware 但只读。其项目管理 Tool 不会主动执行：

git add
git commit
git checkout
git switch
git merge
git rebase
git push
git tag
git reset

研发 Agent 仍可使用其他已经授权的 Tool 执行正常 Git 操作。关键边界在于：权威版本事实来自 Host / Revision Provider，而不是 Agent 自己声称测试的是哪个 SHA 或 Working Tree 状态。

Artifact 感知、节省 Token 的上下文

软件研发除了结构化生命周期状态，还会产生长篇知识：

Requirement   → 意图 / 需求文档
Feature       → 规格 / 设计
Work          → 实现计划 / 笔记
Verification  → 测试计划 / 证据 / 报告
Release       → 评审 / 发布说明

J4Agent 不试图把所有这些内容复制进数据库，而是：

- 结构化生命周期事实保存在 J4Agent；
- 长篇内容保留在 Workspace / Repository 文档或外部引用中；
- J4Agent 保存研发对象与其 Artifact 之间的关系。

对于 Agent Context，J4Agent 倾向于渐进披露。一个关联的 Artifact 可以暴露简短 Brief：

标题
摘要
关键约束
链接

Agent 仅在真正需要细节时才读取全文。这让 Context 保持有用，而不会把模型上下文窗口变成第二个文档数据库。

结构化事实，而非自我报告的信心

v0.2.0-alpha.1 模型遵循若干原则。

结构化事实是事实源

状态、关系、版本身份、Verification Record、Release 成员关系及其他生命周期事实都以结构化状态保存。长篇文本仍有价值，但不能替代这些事实。

Unknown 表示未解决

缺失信息不会被静默解释成“未实现”“安全”或“完成”。如果某个 Gate 需要一个事实而 J4Agent 不知道它，该事实就仍然是未解决的。

派生状态始终保持派生

Ready Set、流程摘要、兼容性、指导及其他投影从持久事实计算，而不是保存为相互竞争的事实源。

Mutation 必须显式且可审计

面向 Agent 的 Mutation 使用幂等 Operation Identity 与 Revision Check，因此重试安全，过期写入可以被拒绝并返回可恢复的 Guidance。

Verification 历史仍是历史

新的测试尝试会新增 Verification Record。历史 Evidence 不会仅因后续实现变化使其 stale 而被改写。

人类与 Agent 的权限

Agent-native 不等于“由 Agent 决定一切”。 J4Agent 有意将 Agent 可操作的行动，与由 Host 或人类拥有权威的事实和决策分离。

| 能力 | Agent | 人类 / Host |
| --- | :---: | :---: |
| 创建 Requirement / Feature / Work | ✓ | ✓ |
| 请求澄清，并登记产生的研发事实 | ✓ | ✓ |
| 实现并更新 Work | ✓ | ✓ |
| 创建 TestWork 并记录测试尝试 | ✓ | ✓ |
| 分析 Verification / Release Ready 状态 | ✓ | ✓ |
| 观察权威 Workspace / Git Revision 事实 | — | Host |
| 提供可信 Actor / Session Identity | — | Host |
| 决定用户的 Requirement 是否真的完成 | — | 人类 |
| 关闭 Requirement | — | 人类 |

目标是 由人类治理、由 Agent 可操作的研发管理。

一段典型研发旅程

例如：

“在报告页面增加 CSV 导出。”

J4Agent 可以这样组织工作：

用户意图
↓
Requirement
├─ 初始 Requirement Item
├─ Feature：CSV 导出
└─ pending Verification

必要时由 Agent 澄清重要歧义
↓
Production Work
↓
实现
↓
TestWork
↓
Verification Records + Evidence
↓
具备版本意识的 Verification Pass
↓
Release Candidate
↓
Released Feature
↓
Requirement 仍保持 open，直到人类决定
整体用户目标确实完成。

在这段旅程中，Context、Analyze、Workflow Brief 和 Continuation 帮助 Agent 理解当前项目事实，并从正确阶段继续。

Project Center

J4Agent 为人类提供 DSH-native Project Center，用来检查和管理与 Agent 相同的研发事实。

UI 是共享模型上的评审与控制 Surface，不是一套独立的人类专属项目状态。因此，人类与 Agent 操作的是同一组 Requirement、Feature、Work、Verification、Release 与 Revision 事实，而非维护对项目的两套平行解释。

Task Graph

Work 依赖关系被投影为确定性的 Task Graph。该图可以提供：

- 依赖关系；
- Ready Set 投影；
- 阻塞诊断；
- 受 Revision 保护的依赖 Mutation；
- 用于 Work 调度和集成的共享执行视图。

Task Graph 是 Work 事实的一种投影，而不是第二个任务数据库。

J4Agent 不做什么

J4Agent 有意保持窄职责边界。它不是：

- Coding Model 或 Coding Agent；
- 对生成代码正确性的保证；
- 对有意义 Code Review、CI、静态分析或产品判断的替代；
- 会自行创建 Worker 的自主 Agent Scheduler；
- 带有账号和 RBAC 的远程企业事项跟踪服务；
- 接管 Git 历史或自动提交、推送代码的工具。

J4Agent 让围绕 Coding Agent 的研发过程更明确、可持续、可验证。它将 已实现、已测试、已验证 与 已发布 等声明转化为可检查的项目事实，而不是只依赖模型的自我报告。

环境要求

当前 v0.2.0-alpha.1 预发布基线：

- Node.js 24
- DeepSeek Harness >=0.1.1-rc.2
- 用于 Project Center UI 的本地 DSH Web Profile
- J4Agent 应安装到 Coding Agent 使用其 Tool 的 Profile 中

安装

固定使用 v0.2.0-alpha.1 预发布 Tag：

dsh plugin --profile web add github:esonx/dsh-project-j4agent#v0.2.0-alpha.1
dsh web

或者安装 GitHub Release 附带的 Tarball：

dsh plugin --profile web add ./dsh-project-j4agent-0.2.0-alpha.1.tgz
dsh web

关于 clean Profile 验证、升级与卸载行为，参见安装与升级。

快速开始

1. 启动 DSH Web，并从侧边栏打开 J4Agent。
2. 初始化当前 Workspace，选择 Local 或 Git Revision Mode。
3. 创建一个 Requirement。J4Agent 会建立其初始 Requirement Item、Feature 与 pending Verification 结构。
4. 随着实现推进，让 Agent 创建并维护 Work。
5. 通过 TestWork、结构化 Record 和当前 Revision Evidence 完成 Verification。
6. 当已验证的 Features 可以交付时创建 Release。
7. 保持 Requirement open，直到 你 决定整体用户目标确实完成。

一个 J4Agent Project 映射到当前 DSH Workspace。

Agent 与 DSH 集成

J4Agent 暴露面向 Agent 与面向 Host 的生命周期 Surface，而不是要求调用方直接操作其 SQLite 数据库。

Agent Tool Surface 覆盖以下能力：

- 初始化当前 Workspace；
- 读取项目与研发旅程状态；
- 获取聚焦的研发 Context；
- 分析 Requirement / Feature / Verification / Release 的 Ready 状态；
- 创建与更新研发 Work；
- 记录 Verification Evidence 与确认流程；
- 管理 Artifact Link；
- 读取和维护 Task Graph 关系；
- 获取定向流程与命令 Help。

准确的公开 Tool Schema 随 Release 版本化，应被视为合同。有关 Host 集成细节，参见架构。

数据与安全边界

J4Agent 将项目本地状态保存于：

/j4agent/

其中包括项目元数据和 J4Agent SQLite 数据库。

J4Agent 不保存模型服务商 API Key。

当前安全边界面向本地、可信 Host。DSH 与已安装插件共享 Host 进程；可信执行上下文向 J4Agent 提供权威的 Actor、Session、Workspace 与 Revision 事实。

卸载插件并不意味着删除项目数据。支持的信任边界参见安全策略。

从 v0.1.x 升级

[!WARNING]
v0.2.0-alpha.1 引入了破坏性的研发模型升级。升级前请备份已有 J4Agent 项目数据。

从 v0.1.x Work Item 模型迁移到 v0.2.0-alpha.1 Agent-native Lifecycle，同时改变了 Schema 与流程语义。

主要概念变化包括：

- Requirement Item 与实现可追溯性；
- 以 Feature 为中心的交付；
- Production 与 Non-production Work 的区分；
- 持续存在的 Feature Verification；
- TestWork 与 append-only Verification Record；
- 具备版本意识的 Verification 与 Release Gate；
- 显式 Release 成员关系与 Candidate 状态；
- Artifact 关联的研发 Context；
- 幂等的 Agent Command、Audit Fact 与结构化 Continuation。

升级前：

1. 为每个已有项目完整备份 /j4agent/ 目录。
2. 阅读 v0.2.0-alpha.1 的 Release Notes 与安装与升级。
3. 除非 Release Notes 明确说明支持迁移，否则不要假定 v0.1.x 项目数据库可以被 v0.2.0-alpha.1 直接使用。
4. 在替换活动项目环境前，先在非关键副本上验证升级。

设计原则

v0.2.0-alpha.1 模型由一组简明原则指导：

1. 研发事实优先于任务描述：跟踪研发生命周期中真实发生的事情，而不只跟踪某人在事项中写了什么。
2. 需求是持续演进的目标：用户意图可以在整个研发过程中演进，并应始终可追溯到实现。
3. Feature 是稳定的交付单元：Work 与 Verification 围绕可独立交付的能力组织。
4. Work 描述现实：影响生产的变更，与规划或文档工作在本质上不同。
5. Verification 跟随实现事实：相关生产变更发生后，已通过结果不会永久有效。
6. Revision 是证明的一部分：Verification 与 Release 必须知道自己正在评估哪个实现状态。
7. 结构化事实是事实源：Markdown 承载丰富内容；J4Agent 承载生命周期状态、关系与 Gate。
8. Guidance 是投影，不是第二个状态机：Workflow Brief、Continuation 与 Analyze 都由同一持久事实和 Policy 派生。
9. 人类与 Agent 拥有不同权限：当需要产品判断或 Host 观察到的真实事实时，Agent-native 研发仍由人类治理。
10. 保持流程轻量；保持交付 Gate 严格：日常研发可以灵活，而 Verification 与 Release 必须有明确 Evidence。

当前限制

v0.2.0-alpha.1 有意保持 local-first 和轻量。

- 不提供远程多用户服务或企业级 RBAC。
- J4Agent 不是 Agent Scheduler，不会自行创建 Worker。
- J4Agent 无法保证生成代码的语义正确性；它围绕这些代码组织并验证研发过程。
- Local Revision Mode 提供 Snapshot Identity，但不提供 Git 式历史归因。
- J4Agent 的 Git-aware 操作对 Repository History 与 Branch Mutation 保持只读。
- 长篇 Artifact 内容保留在 J4Agent 数据库之外；外部 Artifact 只关联，不会被自动抓取到模型 Context。

关于版本特定限制，参见CHANGELOG.md和 Release Notes。

文档

- 安装与升级
- 用户指南
- 架构
- 安全策略
- 变更记录
- 第三方声明

许可证

Apache License 2.0。

第三方源码与设计溯源记录在 THIRD_PARTY_NOTICES.md。

维护者：esonx

J4Agent 不是由 Agent 操作的 Jira。
它是一套围绕人类与 Agent 实际协作方式设计的研发模型。