h3factory 0.2.0 → 0.2.2

package/README.md

@@ -47,13 +47,13 @@ npm install -g git+https://<TOKEN>@github.com/xiangduo10146814/h3factory.git
 ### 从本地 tarball 安装
 
 ```bash
-npm pack                       # 生成 h3factory-0.2.0.tgz
-npm install -g ./h3factory-0.2.0.tgz
+npm pack                       # 生成 h3factory-0.2.2.tgz
+npm install -g ./h3factory-0.2.2.tgz
 ```
 
 安装时 `postinstall` 会把 `skills/h3factory` 和 `skills/h3yun-dev-assistant` 复制到
-Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun
-的用户技能目录（不存在会创建）。技能更新由安装包管理，会覆盖本地修改。
+Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun /
+CodeBuddy / WorkBuddy 的用户技能目录（不存在会创建）。技能更新由安装包管理，会覆盖本地修改。
 
 ## 快速开始
 
@@ -61,7 +61,8 @@ Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun
 mkdir D:\h3work && cd /d D:\h3work   # 任意工作区目录，别用 System32
 
 h3factory auth status --json   # Agent 第一步：检查凭据，ok=false 就先录 token
-h3factory init                 # 人类交互式录入（或由 Agent 用 auth set --json 写入）
+h3factory init                 # 交互录入 + 写入 AGENTS.md（任何 Agent 都能读到）
+h3factory prompt               # 打印通用提示语，直接贴给任意 Agent
 h3factory doctor               # 检查 Python / 配置 / JWT 是否过期 / 技能
 h3factory demo                 # 复制内置示例项目到 ./projects/demo
 h3factory check demo           # 离线校验，不联网
@@ -105,7 +106,9 @@ JSON
 | `h3factory auth status [--json]` | **凭据门禁**：检查配置与 JWT 是否可用 | 否 |
 | `h3factory auth set --json` | 从 stdin 读 JSON 写入凭据（值不回显） | 否 |
 | `h3factory auth set-token` | 从 stdin 读 token 写入 | 否 |
-| `h3factory init [--no-input]` | 交互生成工作区 config.json | 否 |
+| `h3factory init [--no-input] [--no-agent-md]` | 生成 config.json 并写入 AGENTS.md | 否 |
+| `h3factory agent init` | 只写 AGENTS.md 指令块 | 否 |
+| `h3factory prompt [--short]` | 打印任意 Agent 可用的提示语 | 否 |
 | `h3factory demo` | 复制内置示例项目 | 否 |
 | `h3factory doctor` | 检查运行时、配置、JWT、技能 | 否 |
 | `h3factory check <项目> [表..]` | 本地加载并校验表单定义 | 否 |
@@ -135,6 +138,8 @@ npm 安装后会把技能自动复制到以下用户级技能目录（目录不
 | QwenWork | `~/.qwenworkcn/skills/` |
 | Qoder / QoderWork | `~/.qoder/skills/`、`~/.qoderwork/skills/` |
 | Mulerun | `~/.mulerun/skills/` |
+| CodeBuddy | `~/.codebuddy/skills/` |
+| WorkBuddy | `~/.workbuddy/skills/` |
 
 随包安装两个技能：
 
@@ -163,6 +168,19 @@ CLI 自身也会在 `build/verify/group/import` 启动时做同样的检查，to
 **首选方式**：让客户在自己的终端运行 `h3factory auth set-token`（输入隐藏，token 不进入对话记录）；
 还缺其他字段就运行 `h3factory init`。只有客户主动在对话里贴 token 时，才用上面的 `auth set --json`。
 
+### 通用提示语（不依赖技能加载）
+
+任何 Agent（包括 WorkBuddy / CodeBuddy，或不会自动加载技能的模型）都可以这样用：
+
+```bash
+h3factory prompt          # 打印通用提示语，复制给 Agent
+h3factory prompt --short  # 只要一句话版本
+```
+
+或者在项目目录运行一次 `h3factory init`：它会在工作区写入 `AGENTS.md`，
+Codex 等会读取项目指令的 Agent 下次会话就能自动看到 h3factory 的流程和 token 门禁。
+不读 `AGENTS.md` 的 Agent，直接把 `h3factory prompt` 的输出贴进去即可。
+
 新需求直接对 Agent 说：
 
 ```
@@ -200,7 +218,7 @@ h3factory/
 ```bash
 npm pack --dry-run     # 检查包内容：不得出现 config.json / 业务 projects / logs
 npm pack               # 生成 tarball
-npm install -g ./h3factory-0.2.0.tgz
+npm install -g ./h3factory-0.2.2.tgz
 h3factory check demo   # 冒烟
 ```
 

package/cli.py

@@ -59,6 +59,8 @@ TOOL_SKILL_DIRS = (
     (".qoder", "qoder"),
     (".qoderwork", "qoderwork"),
     (".mulerun", "mulerun"),
+    (".codebuddy", "codebuddy"),
+    (".workbuddy", "workbuddy"),
 )
 
 
@@ -133,7 +135,69 @@ def resolve_targets(proj, sheets, targets):
 
 
 # ---------------------------------------------------------------- commands
+AGENT_MD_BEGIN = "<!-- h3factory:begin -->"
+AGENT_MD_END = "<!-- h3factory:end -->"
+AGENT_MD_BLOCK = """<!-- h3factory:begin -->
+## 氚云表单工厂（h3factory）
+
+本工作区使用 `h3factory`。任何 Agent 会话开始必须先执行：
+
+    h3factory auth status --json
+
+如果 `ok=false`，让用户在自己的终端运行 `h3factory auth set-token`（输入隐藏）
+或 `h3factory init`；`ok=true` 后才允许执行 `build/verify/group/import`。
+
+- 命令：`h3factory --help`
+- 流程：`h3factory docs workflow`
+- 需求澄清：`h3factory docs requirement_checklist`
+- 通用提示语：`h3factory prompt`
+<!-- h3factory:end -->"""
+
+
+def _ensure_agent_md(path):
+    """幂等写入 AGENTS.md 的托管块，保留用户原有内容。"""
+    text = ""
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+    if AGENT_MD_BEGIN in text and AGENT_MD_END in text:
+        pre = text.split(AGENT_MD_BEGIN, 1)[0].rstrip()
+        post = text.split(AGENT_MD_END, 1)[1].lstrip("\n")
+        parts = [p for p in (pre, AGENT_MD_BLOCK, post) if p.strip()]
+        new = "\n\n".join(parts) + "\n"
+    else:
+        new = (text.rstrip() + "\n\n" if text.strip() else "") + AGENT_MD_BLOCK + "\n"
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(new)
+    return path
+
+
+def cmd_agent(args):
+    if args.action == "init":
+        path = _ensure_agent_md(os.path.join(settings.workspace_root(), "AGENTS.md"))
+        print("已写入 h3factory 指令块: %s" % path)
+
+
+def cmd_prompt(args):
+    if args.short:
+        print("用 h3factory 帮我做这个需求：<需求>")
+        return
+    print("""请使用 h3factory 帮我完成以下需求：
+<把需求贴在这里>
+
+执行要求：
+1. 先运行 h3factory auth status --json；若 ok=false，让我运行 h3factory auth set-token 录入 token。
+2. 运行 h3factory docs workflow 和 h3factory docs requirement_checklist，按流程先澄清需求。
+3. 产出 projects/<项目名>/ 设计后停下来让我过目，确认后再 build。""")
+
+
 def cmd_init(args):
+    if not getattr(args, "no_agent_md", False):
+        try:
+            path = _ensure_agent_md(os.path.join(settings.workspace_root(), "AGENTS.md"))
+            print("已写入 Agent 指令: %s" % path)
+        except Exception as e:
+            print("警告: 写 AGENTS.md 失败: %s" % e)
     existing = settings.resolve_config_path()
     if existing:
         print("config.json 已存在（%s），不覆盖。要重填请删除后重跑" % existing)
@@ -816,8 +880,14 @@ def main():
     ap = argparse.ArgumentParser(prog="h3factory", description="h3factory —— 氚云表单工厂")
     ap.add_argument("--version", action="version", version=VERSION)
     sub = ap.add_subparsers(dest="cmd")
-    p = sub.add_parser("init", help="生成配置文件")
+    p = sub.add_parser("init", help="生成配置文件并写入 AGENTS.md")
     p.add_argument("--no-input", action="store_true", help="不交互，只复制模板")
+    p.add_argument("--no-agent-md", action="store_true",
+                   help="不写入工作区 AGENTS.md")
+    p = sub.add_parser("agent", help="写入 AGENTS.md 指令（任意 Agent 通用）")
+    p.add_argument("action", choices=["init"])
+    p = sub.add_parser("prompt", help="打印通用提示语")
+    p.add_argument("--short", action="store_true", help="只输出一句话版本")
     sub.add_parser("demo", help="把内置示例项目复制到工作区")
     p = sub.add_parser("auth", help="凭据状态与录入（agent 第一步）")
     p.add_argument("action", choices=["status", "set", "set-token"],
@@ -870,6 +940,7 @@ def main():
         print("或: h3factory init（交互式录入全部凭据）")
         sys.exit(2)
     {"init": cmd_init, "demo": cmd_demo, "auth": cmd_auth,
+     "agent": cmd_agent, "prompt": cmd_prompt,
      "doctor": cmd_doctor, "docs": cmd_docs,
      "skill": cmd_skill, "check": cmd_check, "list": cmd_list,
      "build": cmd_build, "verify": cmd_verify, "group": cmd_group,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h3factory",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "氚云（H3Yun）表单工厂：需求 → 表单定义 → 建表 → 只读核对 → 代码骨架",
   "license": "UNLICENSED",
   "repository": {

package/scripts/postinstall.js

@@ -27,6 +27,8 @@ const TOOL_DIRS = [
   '.qoder',
   '.qoderwork',
   '.mulerun',
+  '.codebuddy',
+  '.workbuddy',
 ];
 
 function copyDir(src, dest) {

package/skills/h3factory/SKILL.md

@@ -40,11 +40,12 @@ description: 氚云（H3Yun）表单工厂总入口。用户提到氚云自动
 
 ## 工作区与安装
 
-- 命令：`h3factory`（别名即包名；源码目录也可 `python -X utf8 cli.py`）。
+- 命令：`h3factory`（npm 包名 `h3factory`；源码目录也可 `python -X utf8 cli.py`）。
 - **当前目录 = 工作区**；项目在 `./projects/<项目名>/`。
 - 配置查找顺序：`H3FACTORY_CONFIG` → `./config.json` → `~/.h3factory/config.json`；项目级 `projects/<项目名>/config.json` 优先于以上。
 - 首次使用：`h3factory auth status --json` → 需要时 `auth set` 录入 token → `h3factory doctor`。
-- 安装包会把技能自动装到 Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun 的用户技能目录；手动重装用 `h3factory skill install --tool all`。
+- 安装包会把技能自动装到 Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun / CodeBuddy / WorkBuddy 的用户技能目录；手动重装用 `h3factory skill install --tool all`。
+- 不自动加载技能的 Agent，用 `h3factory prompt` 打印通用提示语，或在项目里运行 `h3factory init` 写入 `AGENTS.md`。
 - 查看内置文档：`h3factory docs` 列出，`h3factory docs schema_doc` 打印内容。
 
 ## 标准流程