@nick848/ft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nick848
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# FT（Frontend Toolkit）
+
+FT 是一个**前端开发工具编排层**。它以 [Comet](https://www.npmjs.com/package/@rpamis/comet) 为工作流基座，将 [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) 作为 AI 行为的强制约束，并可选择性接入 [GitNexus](https://www.npmjs.com/package/gitnexus) 代码图谱。
+
+FT **不内置任何 LLM**。它的职责是通过 CLI 命令和 IDE Slash 命令，引导 Cursor、Codex、OpenCode 中的 LLM 完成开发任务。
+
+## 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| **零 LLM** | FT 不做推理、不生成代码，所有智能行为由 IDE 内 LLM 完成 |
+| **Comet 透传** | `/ft-open`、`/ft-build` 等命令透传 Comet 工作流，保持原生能力 |
+| **RTK 压缩** | 子进程长输出自动中间截断，降低 Token 消耗；`--json` 等结构化输出自动放行 |
+| **Karpathy 约束** | 初始化时向三平台注入四条行为准则规则文件 |
+| **GitNexus 可选** | 安装后自动配置 MCP；未安装时能力优雅降级 |
+| **双语支持** | CLI 输出与 AGENTS.md 模板支持 `zh-CN` / `en` |
+
+## 环境依赖
+
+### 必需
+
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| **Node.js** | `>= 18` | FT 运行时 |
+| **npm** | 任意较新版本 | 安装与更新 FT、Comet |
+| **Comet** | 全局安装 | `npm install -g @rpamis/comet` — `ft init` 的强制依赖 |
+
+### 可选
+
+| 依赖 | 安装方式 | 说明 |
+|------|----------|------|
+| **GitNexus** | `npm install -g gitnexus` | 代码图谱与 MCP 符号查询 |
+| **Cursor / Codex / OpenCode** | 各工具官网 | Slash 命令与规则注入的目标 IDE |
+
+### 支持平台
+
+当前版本支持以下 IDE / 开发工具：
+
+- **Cursor**
+- **Codex**
+- **OpenCode**
+
+初始化时可将 Karpathy 规则注入到对应平台，并在已安装 GitNexus 时自动配置 MCP。
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g @nick848/ft
+```
+
+验证安装：
+
+```bash
+ft version
+```
+
+## 快速开始
+
+### 1. 安装前置依赖
+
+```bash
+npm install -g @rpamis/comet
+# 可选
+npm install -g gitnexus
+```
+
+### 2. 在目标项目中初始化
+
+```bash
+cd your-frontend-project
+ft init
+```
+
+`ft init` 将依次执行：
+
+1. 检测 Comet（缺失则阻塞退出）
+2. 检测 Karpathy 规则（内置模板可用则通过）
+3. 交互选择注入目标（Cursor / Codex / OpenCode）
+4. 复制 Karpathy 规则到对应平台目录
+5. 若已安装 GitNexus，自动写入 MCP 配置
+6. 生成 `AGENTS.md`（旧文件备份为 `AGENTS-BAK.md`）
+7. 执行 `comet init`
+8. 提示下一步执行 `/ft-fill-context`
+
+英文初始化：
+
+```bash
+ft init --lang en
+```
+
+### 3. 填充项目上下文
+
+在 IDE 聊天框执行 `/ft-fill-context`，将输出的 Prompt 粘贴给 LLM，由 LLM 编辑 `AGENTS.md` 中的 `[NEEDS LLM INPUT]` 占位符。
+
+### 4. 使用 Comet 工作流
+
+上下文填充完成后，在 IDE 中使用 Slash 命令驱动 Comet 流程，例如：
+
+```
+/ft-design
+/ft-build
+/ft-verify
+```
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `ft init [--lang en\|zh-CN]` | 全流程初始化（依赖检测 → 规则注入 → MCP → AGENTS.md → Comet init） |
+| `ft update` | 更新 FT 自身（`npm update -g @nick848/ft`），不更新 Comet / GitNexus |
+| `ft version` | 打印 FT、Comet、GitNexus 版本号 |
+| `ft help` | 显示帮助信息 |
+
+## Slash 命令
+
+所有 `/ft-xxx` 命令在 IDE 中触发，并自动继承 RTK 输出压缩能力。
+
+### 上下文
+
+| Slash 命令 | 说明 |
+|------------|------|
+| `/ft-fill-context` | 输出结构化 Prompt，引导 LLM 填充 `AGENTS.md` |
+
+> **门禁**：`AGENTS.md` 中仍存在 `[NEEDS LLM INPUT]` 时，Comet 透传类命令会被拦截，须先完成 `/ft-fill-context`。
+
+### Comet 工作流（透传）
+
+| Slash 命令 | 说明 |
+|------------|------|
+| `/ft-open` | Comet `open` |
+| `/ft-design` | Comet `design` |
+| `/ft-build` | Comet `build` |
+| `/ft-verify` | Comet `verify` |
+| `/ft-archive` | Comet `archive` |
+| `/ft-hotfix` | Comet `hotfix` |
+| `/ft-tweak` | Comet `tweak` |
+
+**TTY 处理**：在系统终端中保持 Comet 原生交互；在 IDE 非 TTY 环境中尝试注入 `--non-interactive`，若 Comet 不支持则提示转至系统终端执行。
+
+### GitNexus 图谱
+
+| Slash 命令 | 说明 |
+|------------|------|
+| `/ft-graph-setup` | 安装引导 + MCP 配置重试 |
+| `/ft-graph-init` | 首次构建图谱（`gitnexus analyze`） |
+| `/ft-graph-refresh` | 强制刷新图谱（`gitnexus analyze --force`） |
+| `/ft-graph-handoff` | 图谱摘要 + 引导词 + 更新 AGENTS.md 时间戳 |
+| `/ft-graph-status` | 检查 GitNexus 与图谱索引状态 |
+
+## IDE Slash 配置
+
+FT 不直接修改 IDE，需在各平台中配置自定义命令，统一调用 `ft slash <subcommand>`。
+
+### Cursor
+
+在项目 `.cursor/commands/` 下创建命令文件，例如 `ft-fill-context.md`：
+
+```markdown
+---
+description: Fill AGENTS.md context via FT prompt recipe
+---
+
+Run: ft slash fill-context
+```
+
+或在 Cursor Settings → Commands 中添加，命令内容为：
+
+```
+ft slash fill-context
+```
+
+其他 Slash 同理，将 `fill-context` 替换为对应子命令名（`open`、`design`、`build` 等）。
+
+### Codex / OpenCode
+
+参考各平台自定义 Slash / Command 机制，将触发动作配置为：
+
+```bash
+ft slash <subcommand>
+```
+
+确保 `ft` 在 IDE 子进程的 `PATH` 中可用（全局安装后一般即可）。
+
+## 配置文件
+
+初始化后会在项目根目录生成 `.ft/config.yaml`：
+
+```yaml
+# 语言：zh-CN 或 en
+language: zh-CN
+
+# RTK 压缩层
+rtk:
+  enabled: true
+  auto_trigger_lines: 500      # 超过此行数强制压缩（即使全局关闭）
+  exclude_patterns:            # 匹配则跳过压缩，保留原始输出
+    - "--json"
+    - "--format json"
+    - "--xml"
+
+# 已注入规则的目标工具
+tools:
+  - cursor
+  - codex
+  - opencode
+
+# GitNexus
+gitnexus:
+  graph_path: ".gitnexus/"
+  auto_prompt_in_agents: true
+```
+
+**语言优先级**：CLI 参数（`--lang`）> 配置文件 > 默认 `zh-CN`。
+
+也可使用 `ft.config.json` 等同名配置文件。
+
+## 典型工作流
+
+```
+ft init
+    ↓
+/ft-fill-context  →  LLM 填充 AGENTS.md
+    ↓
+/ft-graph-setup   →  （可选）安装并配置 GitNexus MCP
+/ft-graph-init    →  （可选）构建代码图谱
+    ↓
+/ft-design        →  Comet 设计阶段
+/ft-build         →  Comet 构建阶段
+/ft-verify        →  Comet 验证阶段
+    ↓
+/ft-graph-handoff →  （可选）交接图谱上下文给 LLM
+```
+
+## RTK 输出压缩
+
+FT 拦截子进程 `stdout` / `stderr`，对长文本采用**中间截断**策略：
+
+- 保留前 **200** 行 + 后 **100** 行
+- 中间以 `...... (已省略 X 行) ......` 替换
+- 命令参数含 `--json`、`--format json`、`--xml` 时完全旁路
+- Comet 透传且处于 TTY 交互模式时自动禁用，避免破坏 TUI
+
+## 已知限制
+
+- **AGENTS-BAK 合并**依赖 LLM 判断，超模板章节迁移可能存在轻微随机性
+- **IDE 内 Comet 透传**：若 Comet 不支持 `--non-interactive`，须在系统终端执行对应 `comet` 命令
+- **平台范围**：当前仅支持 Cursor、Codex、OpenCode
+
+## 相关链接
+
+- Comet：`npm install -g @rpamis/comet`
+- Karpathy Skills：https://github.com/multica-ai/andrej-karpathy-skills
+- GitNexus：`npm install -g gitnexus`
+
+## License
+
+MIT