@ultime/cli 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.3 - 2026-11-10
+
+- 修复 `--key=value` 的值含等号时被截断：`--define=KEY=VALUE` 现在完整保留。
+- 包内新增 `llms.txt` / `SKILLS.md` 作为消费侧 AI 入口；`rules/` 留仓，操作约束并入 `AGENTS.md`。
+
 ## 0.1.2 - 2026-11-09
 
 - 移除仓库内遗留的 `bin/ultime.js`：它不是本包的公开入口，引用的路径也已不存在。

package/CONTRIBUTING.md

@@ -2,18 +2,33 @@
 
 > 给贡献者与 AI 的最短协作规则。命令见 [README](./README.md)。
 
-## 工作流
+## Git 流程
 
-1. 从 `main` 切 `feat/<主题>` / `fix/<主题>`。
-2. 完成后 `git rebase main` 再合并；主分支不保留中间提交。
-3. 一次提交一件事，提交信息用 `type(scope): subject`。
+1. 从 `main` 切 `feat/<主题>` / `fix/<主题>` / `docs-<主题>`。
+2. 开发完成后 `git rebase main`；一次提交一件事，提交信息用 `type(scope): subject`。
+3. push 分支并开 PR；CI 必须通过，评论必须解决。
+4. 用 rebase / squash 合并，删除分支；`main` 不保留中间提交。
+5. 不直接 push `main`，不 force push、不删除 `main`；`main` 受保护，管理员也一样。
+6. 发布按包版本打 tag，由 CI 执行；tag 规则见仓库保护设置。
 
 ## 改动规则
 
 - CLI 只做参数 / 路径 / IO / 退出码；配置合法性与产物内容归调用方包。
 - 不 import 任何调用方包的源码，只通过公开包名与 exports 依赖。
 - 不自维护具体项目的字段清单；`schema` 之类由调用方投影。
-- 新增命令或退出码：同步 README、`skills.md`、测试与版本戳。
+- 新增命令或退出码：同步 README、`SKILLS.md`、测试与版本戳。
+
+## Review
+
+提交 PR 前自查五件事：
+
+- **文档**：README / 用法 / 示例是否仍准确；链接、版本、CHANGELOG 是否同步。
+- **注释**：只写为什么、约束、反直觉处；不复述代码。
+- **冗余**：同一事实只有一份正文；新增说明先改真源，其他位置只留指针。
+- **缺漏**：新增能力是否有入口、示例与验证命令。
+- **漂移**：`package.json` / README / `CHANGELOG` / VERSION（及适用的 AI 文档）版本是否一致。
+
+机械检查交给 CI；人审看架构、边界、语义与取舍。
 
 ## 验证
 

package/README.md

@@ -44,6 +44,8 @@ process.exitCode = runCli(spec, process.argv.slice(2), processContext())
 
 `parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`；`-h/--help` 与 `-v/--version` 是保留 flag。
 
+AI 入口：[`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)（能力表）随包发布。
+
 ## 边界
 
 - **零领域依赖**：不 import 任何领域包，也不认识具体业务对象。

package/SKILLS.md

@@ -0,0 +1,42 @@
+# @ultime/cli · 可调用能力
+
+> 定位：AI 可调用的通用命令设施。领域命令不在这里。
+> 适用版本：0.1.x
+> 同步基线：0.1.x（手写；API 变化时同批更新）
+
+---
+
+## 入口
+
+```ts
+import { parseArgs, runCli, processContext } from '@ultime/cli'
+import type { ParsedArgs, CliContext, CliSpec, CommandSpec } from '@ultime/cli'
+```
+
+| 能力 | 输入 | 输出 |
+|---|---|---|
+| `parseArgs(argv)` | 字符串数组 | `{ command, flags, positional }` |
+| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | 退出码；版本 / 帮助 / 未知命令 / 异常由它处理 |
+| `processContext()` | — | `{ cwd, out, err }` |
+
+## `CliSpec`
+
+```ts
+{
+  name: string
+  version: string
+  usage: string
+  commands: Record<string, { help?: string; run(args, ctx): number }>
+}
+```
+
+## 错误语义
+
+- 未知命令：`err` 写错误，`out` 写 usage，返回 1；
+- 命令抛异常：`err` 写 message，返回 1；
+- 版本 / 帮助：返回 0，不执行命令。
+
+## 反例
+
+- 把 `--check` 当成 cli 内置 flag：它属于调用方的命令。
+- 在 cli 里读具体项目配置：IO 与配置语义属于调用方命令。

package/dist/index.js

@@ -14,16 +14,17 @@ function parseArgs(argv) {
 			continue;
 		}
 		if (token.startsWith("--")) {
-			const [key, inline] = token.slice(2).split("=", 2);
-			if (inline != null) {
-				flags[key] = inline;
+			const body = token.slice(2);
+			const equal = body.indexOf("=");
+			if (equal !== -1) {
+				flags[body.slice(0, equal)] = body.slice(equal + 1);
 				continue;
 			}
 			const next = argv[i + 1];
 			if (next && !next.startsWith("-")) {
-				flags[key] = next;
+				flags[body] = next;
 				i += 1;
-			} else flags[key] = true;
+			} else flags[body] = true;
 			continue;
 		}
 		if (!command) command = token;

package/llms.txt

@@ -0,0 +1,16 @@
+# @ultime/cli · AI 索引
+
+适用版本：0.1.x
+
+## 去哪找
+
+- 怎么用：[README.md](./README.md)
+- 可调用能力：[SKILLS.md](./SKILLS.md)
+
+## 机器入口
+
+- 公共出口：`@ultime/cli` 的 `parseArgs` / `runCli` / `processContext` 与类型。
+
+## 边界
+
+- 通用设施，不含任何领域命令；读盘写盘归调用方。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
   "keywords": [
     "argument-parser",
@@ -24,6 +24,8 @@
     "dist",
     "src",
     "README.md",
+    "llms.txt",
+    "SKILLS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md"
@@ -49,7 +51,7 @@
     "@types/node": "^22.20.5",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
-    "vite-plus": "1.4.0"
+    "vite-plus": "1.5.1"
   },
   "engines": {
     "node": ">=22.18"

package/src/args.ts

@@ -27,17 +27,18 @@ export function parseArgs(argv: string[]): ParsedArgs {
       continue
     }
     if (token.startsWith('--')) {
-      const [key, inline] = token.slice(2).split('=', 2)
-      if (inline != null) {
-        flags[key] = inline
+      const body = token.slice(2)
+      const equal = body.indexOf('=')
+      if (equal !== -1) {
+        flags[body.slice(0, equal)] = body.slice(equal + 1)
         continue
       }
       const next = argv[i + 1]
       if (next && !next.startsWith('-')) {
-        flags[key] = next
+        flags[body] = next
         i += 1
       } else {
-        flags[key] = true
+        flags[body] = true
       }
       continue
     }