# @fooksky/lodestar 中文文档

规范地址：https://npmcn.com/package/%40fooksky/lodestar/

版本：0\.2\.11
npm 元数据更新时间：2026-11-14T00:37:35.632Z
中文译文更新时间：2026-11-15T07:59:00.875Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fooksky/lodestar
原文对照：https://npmcn.com/package/%40fooksky/lodestar/?lang=original
项目主页：https://github.com/urzz/lodestar#readme
源码仓库：https://github.com/urzz/lodestar

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：147 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：2 个
- peer 依赖：@deepseek-ai/cordis ~4\.1\.0，@deepseek-ai/dsh-fs 0\.2\.2-rc\.1，@deepseek-ai/dsh-skill 0\.2\.2-rc\.1，@deepseek-ai/dsh-tools 0\.2\.2-rc\.1，@deepseek-ai/dsh-sandbox 0\.2\.2-rc\.1，@deepseek-ai/dsh-subprocess 0\.2\.2-rc\.1，@deepseek-ai/dsh-system-prompt 0\.2\.2-rc\.1，@deepseek-ai/dsh-sandbox-policy 0\.2\.2-rc\.1，@deepseek-ai/dsh-working-directory 0\.2\.2-rc\.1，@deepseek-ai/dsh-agent-preset-registry 0\.2\.2-rc\.1
- 首次发布：2026-11-07T15:31:13.966Z
- 最新版本发布：2026-11-14T00:37:35.409Z
- 近 30 天下载量：2328（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

本地 DSH 开发工作流程技能和结构化变化状态

## 安装

```sh
npm install @fooksky/lodestar
```

也可以使用：`pnpm add @fooksky/lodestar`、`yarn add @fooksky/lodestar`、`bun add @fooksky/lodestar`

## README

# Lodestar

Lodestar 是 DeepSeek Harness（DSH）的开发工作流插件，帮助 Agent 确认需求、评审方案、获得实施授权，再执行、验证和交付。项目内的文档与结构化状态让工作可恢复；仅设计任务也能记录设计交付。

## 提供什么

-   **`lodestar` skill**：指导需求澄清、设计取舍、授权判断、任务组织和验收。
-   **`lodestar_change` 工具**：维护 change 的文档版本、决定、验收项、执行引用、验证记录及流程状态，校验阶段前置条件。
-   **可选「Lodestar · 开发工作流」模式**：默认对齐标准模式能力，提供能力组开关和流程提示，复用部署已有的 Teams 等扩展；模式组件默认关闭。

模式默认装配与标准模式对齐的原生能力，支持按能力组配置开关；不会安装缺失的宿主依赖、复制 profile、选择模型或扩大权限。写代码、测试和协作使用 DSH 原生能力；授权的含义与证据是否充分由 Lead 判断。Lodestar 不创建分支、不跨需求调度，也不自动提交、推送或发布。

## 开始使用

通过 DSH 的插件管理安装 `@fooksky/lodestar` 并启用核心插件。需要 Node.js 24+、Git，以及提供文件、工作目录和 subprocess 服务的兼容 DSH 宿主；兼容版本见 [package.json](https://npmcn.com/package/%40fooksky/lodestar/package.json)。

在会话中加载 `lodestar` skill，再说明目标：

> 帮我设计并实现这个功能：……
> 
> 继续 change `20261108-example`，先检查状态和未完成事项。
> 
> 这次只需要设计方案，先不要实施。

想法尚不清楚时，可先做可选发现，分清问题、证据与假设，再决定进入交付、补证据或停止；目标明确的小工具或已有 PRD 可直接复用材料。跨 change 的共识保存在现有项目文档中，按需形成项目基线，再将首个可运行、可验收的完整切片交接到既有 intent/spec。无需另建项目状态或全套模板，详见[项目启动与切片交接](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/references/inception.md)。

intent、spec 与核心架构方案需要人工确认，可合并展示与审核；来源明确、范围匹配且未撤回的确认直接复用。审核与实施授权有效后，调查、普通实现细节、局部修复和相关验证自主推进，实质范围或核心架构变化才确认差异。普通“设计并实现”不代表已审核未来方案。本版受管流程不支持免审实施：缺少有效审核时会说明能力边界，可继续已授权调查和方案；用户坚持免审则暂停，不反复追问或伪造 `spec-review`，也不把状态外实施宣称为受管成功。

若需要模式入口，进入侧栏「插件」→「已安装」→ `@fooksky/lodestar` 详情，在「包含的组件」中启用默认关闭的 `dev-workflow-preset`，再于新会话开始前选择「Lodestar · 开发工作流」。已有会话可直接加载 skill；选择模式本身不构成实施授权。支持模式指南的宿主可展示「模式说明 / 如何使用」；旧宿主会忽略指南字段，仍可阅读随包文档。完整步骤、能力要求与恢复方法见 [使用指南：模式说明 / 如何使用](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/USER_GUIDE.md)。

启用预设后，点击 `dev-workflow-preset` 行的配置入口即可勾选能力组、保存或恢复默认。更改用于新会话，已有会话保留原装配。详见 [能力开关](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/USER_GUIDE.md#%E8%83%BD%E5%8A%9B%E5%BC%80%E5%85%B3)。

## 材料与工作区

默认一个独立需求对应一个 change、一条分支、一个 worktree 和一个 Lead。由用户或外部助手先准备工作区；代码、知识、change 材料和需保留的证据均在本 worktree 内维护。

材料保存在 `.dev-docs/changes/<change-id>/`：`intent.md` 记录真实需求，`spec.md` 记录方案与验收，实施授权后才创建 `plan.md`；`state.json` 由工具维护版本与关联。仅设计交付不需要实施计划。工具接受 `schemaVersion: 2`，旧格式或损坏记录会报错，不自动迁移或修复。业务操作会检查对应阶段的前置条件并自动推进阶段，不能把已执行、已验证的新增记录留在 intent 来绕过授权；真实退回与历史证据仍保留。

每次调用 `lodestar_change` 显式传入 `projectRoot`。Git 项目根须与调用 Agent 的工作目录属于同一 checkout，普通目录须位于 Agent 工作目录内。`workspace` 观察工作区，`list` 和 `get` 读取状态，`create` 创建 change，`update` 以 `expectedRevision` 原子提交领域操作。`archive` 用于显式迁移历史已关闭目录，参数为 `projectRoot`、`changeId` 和 `expectedRevision`；不重新 close，也不改写原状态、revision 或关闭时间。

```json
{"action":"workspace","projectRoot":"."}
```

知识按需渐进加载：先读简短入口，再定位相关主题/章节，确有问题才追溯证据；禁止全库加载或递归展开。每次交付都检查稳定知识增量，更新唯一主题权威与入口；主题独立于 change，必要内容先整理到长期路径。新 `close.knowledge` 用结构化 `updated`（summary、refs）或 `no-change`（reason），历史字符串只读兼容。工具仅检查既有 index 加本次 updated.refs；no-change 和历史 archive 仅检查既有 index，不扫描 knowledge/ 或递归读取链接正文。Lead 仍负责声明完整与内容真实。详见 [知识维护与 close 示例](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/references/knowledge.md)。

close 成功后目录迁至 `.dev-docs/changes/archive/<change-id>/`，归档只读；设计关闭后实施须新建 change。迁移要求 Linux GNU coreutils 并沿用宿主沙箱。局部重验只替代共同验收项的证据；旧版错误通过的 deliver/done 可能因未重验失败报告 `INVALID_STATE`，应保留原文件并诊断，不自动修复。归档中断和历史兼容见 [恢复参考](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/references/recover.md)。

流程规则见 [skill](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/SKILL.md)，工作区规则见 [工作区参考](https://npmcn.com/package/%40fooksky/lodestar/skills/dev-workflow/references/workspace.md)，确切参数见 [工具 schema](https://npmcn.com/package/%40fooksky/lodestar/src/schema.js)。

采用 [MIT 许可证](https://npmcn.com/package/%40fooksky/lodestar/LICENSE)。[GitHub 源码仓库](https://github.com/urzz/lodestar) 为私有仓库，npm 包公开分发；维护约定、历史设计与测试材料保留在源码仓库，不随包分发。

## 常见问题

### @fooksky/lodestar 是什么？

本地 DSH 开发工作流程技能和结构化变化状态

### 如何安装 @fooksky/lodestar？

在项目目录运行 npm install @fooksky/lodestar，或使用 pnpm add / yarn add / bun add。

### @fooksky/lodestar 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fooksky\_\_lodestar 是否存在。

### @fooksky/lodestar 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fooksky/lodestar 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fooksky/lodestar 可以商用吗？

@fooksky/lodestar 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fooksky/lodestar 的下载量有多少？

根据 npm 官方下载统计，@fooksky/lodestar 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,328 次，日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fooksky/lodestar 还在维护吗？

最新版本 0\.2\.11 发布于 2026/11/14（1 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/11/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。