@zythegit/agent-hub 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +72 -41
  2. package/dist/ahub.js +335 -268
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # AgentHub (`ahub`)
2
2
 
3
- > 跨 AI 编码客户端(Claude / Codex / Pi / Antigravity / Qoder / Trae 等)的规范同步、经验学习与技能分发平台。
3
+ > 跨 AI 编码客户端(Antigravity / Qoder / Claude / Codex / Pi / Trae 等)的双层规范投影、经验学习与技能分发平台。
4
4
 
5
- 一处维护规范,多处秒级更新;物理隔离个人与公司资产;支持免编译通过配置扩展任意新 Agent。
5
+ 系统级与项目级双层正交零双投;Always-On 单槽位消除重复上下文;物理隔离个人(`personal`)与公司(`company`)双域资产;支持免编译配置扩展任意新客户端及变体。
6
+
7
+ > 📘 **深入设计文档与复制即用示例**:
8
+ > - 架构需求与投影矩阵:[docs/06-SYSTEM-AND-PROJECT-SCOPE-PRD.md](./docs/06-SYSTEM-AND-PROJECT-SCOPE-PRD.md)
9
+ > - 双层 SoT 配置、产物对照与端到端命令流:[docs/07-BEST-PRACTICES-EXAMPLES.md](./docs/07-BEST-PRACTICES-EXAMPLES.md)
6
10
 
7
11
  ---
8
12
 
@@ -22,7 +26,7 @@ agent-hub --version
22
26
  ### 方式 2:免安装直接执行(npx)
23
27
 
24
28
  ```bash
25
- npx @zythegit/agent-hub sync --all
29
+ npx @zythegit/agent-hub sync
26
30
  ```
27
31
 
28
32
  ### 方式 3:从源码本地构建
@@ -39,91 +43,118 @@ npm link
39
43
 
40
44
  ## 常用命令速查
41
45
 
42
- | 全称命令 | 说明 | 行业常用简写 / 别名 |
46
+ | 全称命令 | 说明 | 常用简写 / 别名 |
43
47
  | :--- | :--- | :--- |
44
- | `ahub sync --all` | 一键同步全部项目规则与技能 (日常最高频) | `ahub sync -a` / `ahub s` |
45
- | `ahub sync <项目名>` | 仅同步指定的一个项目 | `ahub s <项目名>` |
46
- | `ahub doctor` | 全项目健康体检与配置巡检 | `ahub d` |
48
+ | `ahub sync` / `ahub sync --all` | **默认先同步系统级(Layer 0),再同步全部项目** | `ahub s` / `ahub sync -a` |
49
+ | `ahub sync --system` | 仅同步系统级配置(Rules / Skills / Agents / System MCP) | `ahub sync -g` / `--global-only` |
50
+ | `ahub sync --projects-only` | 仅批量同步所有项目,不触碰用户主目录 | - |
51
+ | `ahub sync <项目名>` | 仅同步指定单个项目(系统级漂移时末尾提示) | `ahub s <项目名>` |
52
+ | `ahub sync --prune-legacy --dry-run` | 升级迁移:预览并按特征清理历史托管残留(绝不误伤非托管资产) | - |
53
+ | `ahub doctor` | 全量健康体检(双层漂移、重复注入、24KB/Token 预算与域隔离审计) | `ahub d` |
54
+ | `ahub hub restore` | 新机还原本机映射(支持纯 `personal` 单库)并自动同步系统级 | - |
55
+ | `ahub hub detach company --dry-run` | 离职一键卸载公司域预览(含投影/状态清理、跨域复检与 AGY 提醒) | - |
47
56
  | `ahub project list` | 列出当前已纳管的所有项目 | `ahub project ls` |
48
57
  | `ahub project add <路径>` | 纳管新项目并自动侦测技术栈 | - |
49
- | `ahub project remove <项目名> -c` | 解绑项目并安全清理投影生成物 | `ahub project rm <项目名> -c` |
50
- | `ahub learn harvest` | 增量脱敏采集多工具近期会话日志 | - |
51
- | `ahub learn distill` | 提纯会话日志为待审经验卡 | - |
52
- | `ahub learn review` | 终端交互式逐条审核经验卡 | - |
53
- | `ahub learn review --auto` | 免交互自动批量审核 (高分晋升, 低分丢弃) | - |
58
+ | `ahub remove <项目名> --clean` | 解绑项目并按 Manifest 精确清理投影与状态指纹 | `ahub rm <项目名> -c` |
59
+ | `ahub hub remove <hub> --clean` | 按 Hub(`personal\|company\|all`)批量解绑并清理投影 | `ahub hub rm <hub> -c` |
60
+ | `ahub learn harvest` / `distill` / `review` | 增量脱敏采集会话 → 提纯待审卡片 → 交互或 `--auto` 审核晋升 | - |
61
+ | `ahub learn remove <card-id>` | 从 `.local/pending/` 删除指定待审经验卡 | `ahub learn rm <card-id>` |
54
62
 
55
- > 📌 **命令设计原则**:遵循 CLI 行业惯例(如 `git` / `npm` / `docker` / `kubectl`),**文档与帮助全面优先呈现语义明确的全称命令**;仅提供标准动词缩写(如 `list` -> `ls`、`remove` -> `rm`、`--all` -> `-a`),杜绝反直觉的生硬连环缩写。
63
+ > 📌 **命令设计原则**:遵循 CLI 行业惯例,文档与帮助优先展示语义明确的全称命令,辅以标准动词/参数缩写(如 `sync` → `s`、`doctor` → `d`、`list` → `ls`、`remove` → `rm`)。
56
64
 
57
65
  ---
58
66
 
59
67
  ## 核心工作流
60
68
 
61
- ### 1. 初始化(首次使用或换机迁移)
69
+ ### 1. 初始化与换机还原(支持纯个人单库)
62
70
  ```bash
63
- # 首次使用:初始化双 Hub 结构与本机映射
71
+ # 首次使用:初始化双 Hub 骨架与本机映射
64
72
  ahub hub init
65
73
 
66
- # 换新电脑:克隆 SoT 仓库后一键重建路径映射与全端软链
74
+ # 换新电脑:克隆 SoT 仓后一键还原(仅克隆 personal 仓亦可成功),
75
+ # 自动串联 ahub sync --system 并汇总缺失的 ${ENV_VAR} 环境变量清单
67
76
  ahub hub restore
68
77
  ```
69
78
 
70
- ### 2. 纳管新项目
79
+ ### 2. 旧仓迁移与日常双层同步
71
80
  ```bash
72
- # 自动检测技术栈(Vue/Spring Boot/TS/Python),自动绑定对应 Profile 与生成覆盖层模版
81
+ # 从旧版升级时:先预览历史重复规则/错放 MCP 清理依据,确认后执行
82
+ ahub sync --prune-legacy --dry-run
83
+ ahub sync --prune-legacy
84
+
85
+ # 纳管新项目并触发同步
73
86
  ahub project add /path/to/project
87
+ ahub sync <项目名>
74
88
 
75
- # 触发首次同步
89
+ # 日常最高频:系统级 + 全部项目一次同步到位
76
90
  ahub sync
91
+
92
+ # 仅更新全局习惯 / 通用 Skill / 系统级 MCP
93
+ ahub sync --system
77
94
  ```
78
95
 
79
96
  ### 3. 会话经验学习闭环
80
97
  ```bash
81
- # 1. 增量采集并强制脱敏 (Token/密码/凭据)
98
+ # 1. 多端增量采集并强制脱敏(Token / 密码 / 凭据)
82
99
  ahub learn harvest --since 7d
83
100
 
84
- # 2. 提纯为经验待审卡片 (存入 .local/pending/)
101
+ # 2. 提纯为待审经验卡(存入 .local/pending/)
85
102
  ahub learn distill
86
103
 
87
- # 3. 审核卡片(支持终端交互确认,或基于置信度一键自动批量处理)
104
+ # 3. 审核晋升(支持终端交互确认,或 --auto 按置信度批量处理)
88
105
  ahub learn review --auto
89
106
 
90
- # 4. 同步至各端生效
91
- ahub sync --all
107
+ # 4. 双层同步至各端生效,并运行健康体检
108
+ ahub sync && ahub doctor --all
92
109
  ```
93
110
 
94
- ### 4. 项目解绑与清理
111
+ ### 4. 解绑项目与离职一键卸载公司域
95
112
  ```bash
96
- # 方式 A:仅解绑项目,保留项目中的现有文件
97
- ahub project remove <项目名>
113
+ # 解绑单个项目并按 Manifest 精确清理(托管块外手写内容与非托管技能 100% 完好保留)
114
+ ahub remove <项目名> --clean
98
115
 
99
- # 方式 B:解绑并安全清理(剥离 AGENTS.md 托管块,清理 .claude/.agents/.qoder/.trae 等目录)
100
- # (你在托管块外面手写的内容 100% 完好保留!)
101
- ahub project remove <项目名> --clean
116
+ # 离职一键卸载公司域:先预览影响面,确认后清理公司项目投影/状态/经验卡并完成跨域复检
117
+ ahub hub detach company --dry-run
118
+ ahub hub detach company
119
+
120
+ # 校验剩余个人项目健康
121
+ ahub doctor --all && ahub sync
102
122
  ```
103
123
 
104
124
  ---
105
125
 
106
- ## 免代码扩展新 Agent 工具
126
+ ## 免代码扩展客户端与变体
107
127
 
108
- 如需支持新出的人工智能编码工具(例如 Cursor、Windsurf 等),无需修改源码或重新编译,直接在配置根目录的 `custom-targets.yaml` 中声明:
128
+ 在配置根目录的 `custom-targets.yaml` 中,可通过 `extends` + `home_root` 一行适配内置客户端变体,或通过 `system` / `project` 声明全新工具(向下兼容 v1 扁平字段):
109
129
 
110
130
  ```yaml
111
131
  targets:
132
+ # 一行继承内置 qoder 并重定向主目录(适配 Qoder CN 版)
133
+ qoder-cn:
134
+ description: "Qoder CN IDE / CLI"
135
+ extends: qoder
136
+ home_root: "~/.qoder-cn"
137
+
138
+ # 声明全新客户端(示例:Cursor)
112
139
  cursor:
113
140
  description: "Cursor IDE"
114
- rules:
115
- single_file: ".cursorrules"
116
- mcp:
117
- path: ".cursor/mcp.json"
118
- skills_dir: ".cursor/skills"
141
+ project:
142
+ rules:
143
+ single_file: ".cursorrules"
144
+ dir: ".cursor/rules"
145
+ ext: ".mdc"
146
+ mcp:
147
+ path: ".cursor/mcp.json"
148
+ local_path: ".cursor/mcp.local.json"
149
+ skills_dir: ".cursor/skills"
119
150
  ```
120
151
 
121
- 保存后直接执行 `ahub sync --all` 即可全局自动生效。
152
+ 保存后执行 `ahub sync` 即可生效。更多完整示例见 [docs/07-BEST-PRACTICES-EXAMPLES.md](./docs/07-BEST-PRACTICES-EXAMPLES.md)。
122
153
 
123
154
  ---
124
155
 
125
156
  ## 跨平台说明
126
157
 
127
- - **Windows**:技能通过 Directory Junction (`mklink /J`) 软链分发,改一处处处实时生效,免管理员权限。
128
- - **macOS / Linux**:自动采用原生 Symbolic Link (`ln -s`)。
129
- - **受限环境**:自动降级为带哈希校验的实体拷贝。
158
+ - **Windows**:Skills 通过 Directory Junction(`mklink /J`)软链分发,改一处处处实时生效,免管理员权限。
159
+ - **macOS / Linux**:自动采用原生 Symbolic Link(`ln -s`)。
160
+ - **受限环境**:自动降级为带 `.agenthub-skill-manifest.json` 校验清单的实体拷贝。