AstraWorks

AstraWorks 是一个可全局安装、项目隔离的本地 AI 工作系统。npm 包提供不可变 CLI、执行引擎、公共多项目工作台、Skill 基线、Loop 模板与数据 Schema；业务项目只保存自己的工作定义和数据。

核心模型

AstraWorks 的基本管理单元不是一条任务，也不是一个 Agent 进程，而是项目工作单元：一个项目代表一名员工负责的一段完整业务闭环。员工可以拥有多个项目，但每个项目分别保存自己的目标、素材、知识、Skill、Loop、工作、经验和工作台定义。

全局安装的 AI 工作引擎围绕当前项目协同运行四类能力：

• Loop 引擎：重复执行项目业务流程，并运行自验证、自修复、自学习和自成长循环。
• 知识系统：把项目素材与已验证结果转化为可追溯、可复用的本地知识，持续补充 Agent 上下文。
• Skill 能力系统：向项目 Agent 提供可复用的工作和扩展能力，例如创建新 Loop、新工作台或调用外部系统。
• 工作台引擎：把项目任务、知识和工作结果投影为员工可直接操作的业务界面，同时把内部运转机制收纳到工作引擎管理面。

这些能力不是独立的信息展示模块，而是同一个项目闭环中的协作机制。它们共同形成“观察项目状态 -> 推进工作 -> 验证结果 -> 沉淀知识与经验 -> 改进下一轮执行”的递归运行链。

平台源码

astraworks/
├── bin/                    npm CLI 入口
├── src/
│   ├── cli/                参数解析与输出适配
│   ├── application/        CLI 与 Dashboard 共享用例编排
│   ├── contracts/          公开 Schema 的运行时校验契约
│   ├── core/               项目上下文、进程、日志、版本
│   ├── projects/           初始化、注册、升级、诊断与统一项目布局
│   ├── agents/             Agent 检测、Skill 安装、能力清单
│   ├── service/            常驻 Engine Daemon 生命周期与运行状态
│   ├── scheduler/          Cron 发现、持久化队列、Worker 与中断恢复
│   ├── loops/              Loop 注册、执行、报告、进化
│   ├── todo/               待办主数据、甄别、路由、执行
│   ├── wiki/               素材摄入、分类、编译、健康检查
│   ├── experience/         经验收集、沉淀、晋升、移除
│   ├── governance/         Engine Finding、结构治理与自动修复
│   ├── integrations/       外部 CLI 和业务系统 Adapter
│   ├── storage/            JSONL、原子写、锁、迁移
│   └── dashboard/          公共工作台后端与 ui/ 前端源码
├── skills/                 初始化时安装给 Agent 的 Skill 基线
├── packages/
│   ├── agent-kit/          公开 Agent 协议、能力目录与 Skill npm 包
│   └── dsh-plugin/         DeepSeek Harness 原生宿主插件
├── templates/              默认项目、Loop、策略和 Agent 入口模板
├── schemas/                平台公开数据契约
├── test/                   平台源码自验证场景
└── dist/                   Engine 与 Dashboard 的统一构建产物

安装后形态

~/.astraworks/
├── registry/projects.jsonl
└── runtime/

<business-project>/
├── AGENTS.md or CLAUDE.md
├── .agents/skills/ or .claude/skills/
├── agents/                     # AgentPort Agent 源定义
├── docs/                       # AgentPort 项目文档
├── environments/               # 运行环境声明
├── evals/                      # 共享评测资产
├── harness-profiles/           # Harness 配置
├── hooks/                      # 生命周期 Hook
├── knowledge/                  # Agent 知识源
├── loops/                      # AgentPort Loop 定义
├── mcp/                        # MCP 服务定义
├── orchestrations/             # 多 Agent 编排
├── schemas/                    # AgentPort Schema
├── scripts/                    # 工程脚本
├── skills/                     # AgentPort Skill 源码
├── workbenches/                # Agent 工作台源码
├── catalog.yaml                # AgentPort 组件注册表
└── .astraworks/
    ├── project.yaml
    ├── install.json
    ├── capabilities.json
    ├── policies/
    ├── integrations/
    ├── agents/                 # 安装实例与生命周期记录
    ├── dashboard/              # 已物化的 Agent 工作台
    ├── data/
    ├── loops/
    ├── reports/
    ├── experience/
    ├── raw/<business>/<type>/
    └── llm-wiki/

业务项目不会安装 engine/、dashboard/、runtime/、test/ 或 .astraworks/skills/。Agent 通过已安装 Skill 理解工作方式，通过全局 astraworks CLI 调用确定性能力；Dashboard 由全局 npm 包统一提供并支持项目切换。

公开包

@astraworks/agent-kit   AgentPort 使用的协议、能力目录和 Agent Skills
@astraworks/cli         全局 AI 工作引擎、Daemon、Scheduler、Dashboard 与 CLI
@astraworks/dsh-astraworks  内嵌 Engine Runtime 的 dsh 原生插件与 Web Adapter

skills/ 是 Agent Skill 的唯一源码。@astraworks/agent-kit 构建时生成带摘要的 Skill 目录和公开契约；@astraworks/cli 依赖该包完成项目初始化与升级，不再在自己的 npm 制品中内嵌 Skills。

Skill 目录统一使用 <module>-<capability> 命名，例如 loop-builder、knowledge-manager、project-operator。名称必须是小写字母、数字和连字符，并以明确的能力词 builder、initializer、manager 或 operator 结尾；构建阶段会拒绝不符合规范或与 SKILL.md frontmatter 不一致的名称。

AgentPort 只依赖 @astraworks/agent-kit，不依赖完整 Engine。Adapter 从 Kit 解析并锁定所需 Skill，再将其物化到 Codex、Claude 或其他目标 Agent 安装包。

AstraWorks 工作引擎的 Agent 中心负责 Agent 的创建、定义校验、测试评测契约、生命周期、目标安装包编译和安装。随项目安装的 agent-builder Skill 引导用户定义具体工作、输入输出、执行流程、能力绑定、人工审核边界、三类基线测试和质量发布门槛，并将完整 AgentPort 源码工程保存到项目根目录：agents/<agent-id>/ 只保存本项目正在开发的 Agent 定义，docs/、evals/、harness-profiles/、hooks/、knowledge/、loops/、mcp/、orchestrations/、schemas/、scripts/、skills/ 是可复用工程资产，catalog.yaml 是源码注册表。默认的 AstraWorks Adapter 将执行契约编译为 <agent-id>-<version>.agent.zip，只携带编译后的员工 Skill 和 bindings.yaml 明确引用的资源，并在编译成功后安装到当前源码项目；发布、审阅或 CI 可用 --no-install 保持只构建。开发态安装会校验并复用项目已有的绑定 Skill，不接管其所有权。安装不会在 agents/ 下创建投影；安装记录、员工元数据和权威运行 Skill 保存在 .astraworks/agents/<agent-id>/，绑定的 Loop、MCP、Knowledge、Hook、Harness Profile、Orchestration 和 Workbench 分别物化到 .astraworks/<资源类型>/<资源 id>/。

Agent 中心可以配置多个 HTTP/HTTPS 远端目录。目录只提供可发现的版本元数据，安装状态仍归属于用户选择的 AstraWorks 工作目录；远端安装包进入全局内容寻址缓存并通过 SHA-256 校验后才会安装。工作台汇总所有注册项目的安装实例，安装前要求选择工作目录，已有旧版本时切换为升级，同版本禁止重复升级，停用和卸载始终作用于安装所属项目。目录不可用时可继续查看标记为“使用缓存”的上次目录数据。

安装目标可以是已注册项目，也可以是新的绝对目录。安装弹窗可浏览并新建目录；新目录会先自动初始化完整工作引擎，再安装最小员工入口、绑定运行资产、绑定 Skill 和项目级 agent-<id> Skill，不安装开发源码。在 DSH 中安装成功后，该目录会同时创建为 DSH 工作区会话并显示；DSH 新增工作区后首次访问 AstraWorks 时也执行同一套幂等初始化。

官方 AgentHub 固定为 https://git.talentseek.com.cn/agenthub/agenthub，升级 AstraWorks 后会自动出现在 Agent 中心，无需用户注册。数字化员工列表统一读取 Catalog，不再混入当前项目的本地构建记录；仓库根目录保存 catalog.json，远端 Agent 安装包由同一仓库的 packages/ 目录统一管理。团队也可以额外注册公开 GitLab 项目或 HTTP/HTTPS Catalog；仓库布局和发布格式见 docs/agenthub-repository-contract.md。

astraworks agent catalog-add https://example.com/agents/catalog.json --name '团队目录'
astraworks agent catalog-add https://git.example.com/team/agenthub --kind gitlab-project --name '团队 AgentHub'
astraworks agent catalog-refresh
astraworks agent install-remote hr-agent --catalog catalog-example-com-ab12cd34 --project /path/to/project
astraworks agent upgrade hr-agent --catalog catalog-example-com-ab12cd34 --project /path/to/project

DeepSeek Harness 用户只需在目标 profile 安装一次 @astraworks/dsh-astraworks。插件与 dsh 在同一进程运行，直接调用嵌入式 AstraWorks Runtime，不启动独立 CLI 子进程或 Engine Daemon。dsh Web 侧栏在“工作区”上方提供全局“工作台”入口，点击后在右侧主内容区展示完整工作引擎；Session 内的“看板”则只展示当前项目。已启用 Agent 自动成为该项目可调用的 agent-<id> Skill。

安装与初始化

npm install -g @astraworks/cli

# 安装完成后，全局 Engine、Scheduler 和 Dashboard 已自动启动
astraworks service status

cd <your-project>
astraworks project init . \
  --agents auto \
  --role '<岗位>' \
  --scenario '<场景>' \
  --biz-types '<业务类型A>,<业务类型B>'

astraworks project doctor .
astraworks project upgrade .
astraworks loop status

--agents auto 根据项目内 Agent 入口和标准目录选择安装目标。当前支持 Codex、Claude Code 与 Cursor；初始化结果记录在 .astraworks/capabilities.json。

默认安装端口为 4173。安装生命周期会把 Engine 启动成功作为安装成功条件；如果端口被占用或 Engine 启动失败，npm 安装会报错，避免产生“CLI 已安装但工作台不可用”的半成功状态。可通过 ASTRAWORKS_PORT 和 ASTRAWORKS_POLL_MS 覆盖默认值；仅在自动化构建等明确不需要常驻服务的环境中使用 ASTRAWORKS_AUTO_START=0 npm install -g ... 跳过自动启动。

常驻 Engine

安装完成后，全局唯一的 Engine Daemon 已经托管 Dashboard 和所有已注册项目的自动 Loop。以下命令用于查看、恢复和维护服务：

astraworks --project . service start --port 4173 --open
astraworks service status
astraworks service logs --lines 120
astraworks service restart
astraworks service stop

service start 启动脱离当前终端的 Node 后台进程。Daemon 托管公共多项目 Dashboard，并由 Scheduler 持续扫描 ~/.astraworks/registry/projects.jsonl 中的项目。技术运行态只写入：

Dashboard 会定期检查 npm 新版本；发现更新后在顶部显示升级入口。一键升级由本机后台进程安装固定目标版本，升级已注册项目基线，并按原端口自动重启 Engine。升级状态与日志保存在 ~/.astraworks/runtime/engine/。

~/.astraworks/runtime/
├── engine/
│   ├── engine.pid
│   ├── engine.lock
│   ├── engine.log
│   └── service.json
└── scheduler/
    ├── schedules.json
    └── jobs.jsonl

业务项目中的 Loop 通过 .astraworks/loops/<slug>/config.json 声明调度：

{
  "schedule": {
    "enabled": true,
    "cron": "*/10 * * * *",
    "timezone": "Asia/Shanghai",
    "runOnStart": false
  }
}

Scheduler 支持标准五字段 Cron 的通配符、列表、范围和步进。到期任务先写入持久化 JSONL 队列，再以独立 CLI 子进程执行 astraworks --project <path> loop run <slug> --trigger scheduler。Daemon 异常退出后，原来处于 running 的作业会在下次启动时恢复为 queued 并按重试策略继续处理。

astraworks dashboard serve 仍保留为前台临时工作台，适合开发调试；正式日常运行应使用 astraworks service start。

本地 SQLite

业务项目需要本地结构化数据时，可以将项目内 SQLite 注册为连接中心的数据源。连接描述符只保存项目相对路径，默认只读；Agent 和 Dashboard 都必须通过应用层调用，不能直接打开数据库文件。

# 连接现有数据库；不填写 --path 时默认使用 .astraworks/integrations/sqlite/<id>.sqlite
astraworks integrations sqlite add business-db \
  --path .astraworks/integrations/sqlite/business.sqlite \
  --name '业务数据库' \
  --tables customers,orders

astraworks integrations sqlite status business-db
astraworks integrations invoke business-db tables
astraworks integrations invoke business-db table-preview \
  --input '{"table":"customers","limit":20}'
astraworks integrations invoke business-db query \
  --input '{"sql":"SELECT name FROM customers WHERE segment=:segment","params":{"segment":"enterprise"}}'

SQLite 适配器优先使用 Node.js 22+ 的 node:sqlite；Node.js 20 可使用系统 sqlite3 命令。适配器支持连接诊断、表结构发现、表预览和受限查询，禁止写入 SQL、越界数据库路径、未授权表以及超过行数上限的返回结果。个人或项目工作台可在数据源定义中使用 connector 为连接 ID、operation 为 table-preview 或 query 的 integration source，将结果渲染为表格或列表。

架构约束

• src/projects/layout.mjs 是项目目录、工作区、全局运行态和 Schema 路径的唯一布局定义。
• src/loops/paths.mjs 只定义 Loop 自身的配置、状态、历史、报告、版本和锁路径。
• Dashboard 前端源码位于 src/dashboard/ui/，构建后统一输出到 dist/dashboard/ui/。
• schemas/ 中的主数据 Schema 在写盘前由 src/contracts/ 强制校验；校验失败时不得修改文件。
• Engine Daemon 是 Dashboard 与自动 Loop 的唯一常驻宿主；业务项目不得保存 PID、锁、队列或 Engine 副本。
• Scheduler 只执行已注册项目中明确启用的 Loop 调度；单个调度时刻使用确定性 Job ID 防止重复入队。

工作分层

AstraWorks 用工作归属控制员工注意力：

• 员工工作：员工真实承诺、业务动作、审批和业务判断，使用 .astraworks/data/todos.jsonl，展示在首页和任务看板。
• 引擎工作：Engine、Scheduler、Loop、治理、自验证、修复、经验和 Skill 管理，使用 .astraworks/data/findings.jsonl 与运行报告，集中在“工作引擎”工作台。
• 自动修复：引擎偏差先执行确定性修复，再由项目 Agent 有界修复；失败检查必须重跑，没有确定性检查的偏差由下一轮 Loop 复核。
• 经验反补：已验证修复提取为经验并反补 Skill、Loop、知识、Dashboard 和 Agent 入口；经验候选不创建员工待办。

顶层业务导航按“工作台、知识库、连接中心”排列，并且不展示统计数字。任务与知识以全局工作视图聚合所有注册项目，同时保留来源项目与目录；项目自定义看板作为“工作台”下的菜单。Loop、调度、修复、经验、Skills、Agent 能力与外部系统连接都是连接中心的二级管理页面。

用户创建的个人看板及组件布局由 Engine 全局持久化到 ~/.astraworks/runtime/dashboard/home-dashboard.json，使用 Schema 校验、原子写入、文件锁和 revision 冲突控制。浏览器缓存不作为看板主数据源。

全局 Dashboard 只提供程序壳层和项目切换。选中项目后，首页、任务、知识、业务工作台、Loop、Skill、经验、Finding 和运行记录都必须切换到该项目的完整上下文；不同项目的数据、能力和学习结果不得混合。

开发验证

npm run build
npm test
npm run test:package-e2e
npm run pack:check

test/ 只属于 AstraWorks 平台源码，不复制到业务项目。