技能共享实施功能
- 作者仓库星标 1,897
- 作者仓库 skillshare
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @runkids · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 6 步:E2E Runbook(仅限主要功能)
如果该功能满足以下任何条件,则生成 E2E Runbook: 新命令或子命令 对安装/卸载/同步流程的更改 安全相关(审核、哈希验证、回滚) 多步骤用户工作流程(初始化 → 安装 → 同步 → 验证)
第 7 步:阶段和报告
列出所有创建/修改的文件 通过测试证据确认每个验收标准均满足 如果该功能影响 CLI 标志或用户可见的行为,则提醒用户运行`update-docs`
Implement a feature following TDD workflow. $ARGUMENTS is a spec file path (e.g., `specs/my-feature.md`) or a plain-text feature description.
**Scope**: This skill writes Go code and tests. It does NOT update website docs (use `update-docs` after) or CHANGELOG (use `changelog` after).
## Workflow
### Step 1: Understand Requirements
If $ARGUMENTS is a file path:
1. Read the spec file
2. Extract acceptance criteria and edge cases
3. Identify affected packages
If $ARGUMENTS is a description:
1. Search existing code for related functionality
2. Identify the right package to extend
3. Confirm scope with user before proceeding
### Step 2: Identify Affected Files
List all files that will be created or modified:
```bash
# Typical pattern for a new command
cmd/skillshare/<command>.go # Command handler
cmd/skillshare/<command>_project.go # Project-mode handler (if dual-mode)
internal/<package>/<feature>.go # Core logic
tests/integration/<command>_test.go # Integration test
```
Display the file list and continue. If scope is unclear, ask the user.
### Step 3: Write Failing Tests First (RED)
Write integration tests using `testutil.Sandbox`:
```go
func TestFeature_BasicCase(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
// Setup
sb.CreateSkill("test-skill", map[string]string{
"SKILL.md": "---\nname: test-skill\n---\n# Content",
})
// Act
result := sb.RunCLI("command", "args...")
// Assert
result.AssertSuccess()
result.AssertOutputContains("expected output")
}
```
Verify tests fail:
```bash
make test-int
# or run specific test:
go test ./tests/integration -run TestFeature_BasicCase
```
### Step 4: Implement (GREEN)
Write minimal code to make tests pass:
1. Follow existing patterns in `cmd/skillshare/` and `internal/`
2. Use `internal/ui` for terminal output (colors, spinners, boxes)
3. Add oplog instrumentation for mutating commands:
```go
start := time.Now()
// ... do work ...
e := oplog.NewEntry("command-name", statusFromErr(err), time.Since(start))
oplog.Write(configPath, oplog.OpsFile, e)
```
4. Register command in `main.go` commands map if new command
Verify tests pass:
```bash
make test-int
```
### Step 5: Refactor and Verify
1. Clean up code while keeping tests green
2. Run full quality check:
```bash
make check # fmt-check + lint + test
```
3. Fix any formatting or lint issues
## Project Patterns Reference
These patterns appear throughout the codebase. Follow them when implementing new features.
### Handler Split Convention
Large commands are split by concern rather than kept in a single file. When a command handler grows beyond ~300 lines, split it:
| Suffix | Purpose | Example |
|--------|---------|---------|
| `<cmd>.go` | Flag parsing + mode routing (dispatch) | `install.go` |
| `_handlers.go` | Core handler logic | `install_handlers.go` |
| `_render.go` / `_audit_render.go` | Output rendering | `audit_render.go` |
| `_prompt.go` / `_prompt_tui.go` | Decision/prompt logic | `install_prompt.go` |
| `_tui.go` | Full-screen TUI (bubbletea) | `list_tui.go` |
| `_batch.go` | Batch operation orchestration | `update_batch.go` |
| `_resolve.go` | Target/skill resolution | `update_resolve.go` |
| `_context.go` | Mode-specific context struct | `install_context.go` |
| `_format.go` | Output formatting helpers | `log_format.go` |
**Principle**: dispatch file does ONLY flag parsing + mode routing. Logic goes in sub-files.
### Dual-Mode Command Pattern
Most commands support both global (`-g`) and project (`-p`) mode:
```go
func handleMyCommand(args []string) error {
mode, rest, err := parseModeArgs(args)
if err != nil { return err }
switch mode {
case modeProject:
return handleMyCommandProject(rest)
default:
return handleMyCommandGlobal(rest)
}
}
```
Create `<cmd>_project.go` for project-mode handler. Use `parseModeArgs()` from `mode.go`.
### TUI Components (bubbletea)
All interactive prompts use **bubbletea** (not survey). Key components:
- `checklist_tui.go` — shared checklist/radio picker
- `list_tui.go` — filterable list with detail panel
- `search_tui.go` — multi-select checkbox list
Color palette: cyan `Color("6")`, gray `Color("8")`, yellow `#D4D93C`.
Dispatch order: JSON output → TUI (if TTY + items + !`--no-tui`) → empty check → plain text.
### Web API Endpoint
If the feature needs a Web UI endpoint, add `internal/server/handler_<name>.go`:
```go
func (s *Server) handle<Name>(w http.ResponseWriter, r *http.Request) {
// ...
writeJSON(w, result) // 200 OK with JSON
// writeError(w, 400, msg) // for errors
}
```
Register in `server.go` route setup. Branch on `s.IsProjectMode()` for mode-specific behavior.
### Oplog Instrumentation
All mutating commands log to `operations.log` (JSONL):
```go
start := time.Now()
// ... do work ...
e := oplog.NewEntry("command-name", statusFromErr(err), time.Since(start))
e.Args = map[string]any{"key": value}
oplog.Write(configPath, oplog.OpsFile, e)
```
Security scans write to `oplog.AuditFile` instead.
### Step 6: E2E Runbook (Major Features Only)
If the feature meets **any** of these criteria, generate an E2E runbook:
- New command or subcommand
- Changes to install/uninstall/sync flow
- Security-related (audit, hash verification, rollback)
- Multi-step user workflow (init → install → sync → verify)
- Edge cases that integration tests alone can't cover (Docker, network, file permissions)
Generate `ai_docs/tests/<slug>_runbook.md` following the existing convention:
```markdown
# CLI E2E Runbook: <Title>
<One-line summary of what this validates.>
**Origin**: <version> — <why this runbook exists>
## Scope
- <bullet list of behaviors being validated>
## Environment
Run inside devcontainer with `ssenv` isolation.
## Steps
### 1. Setup: <description>
\```bash
<commands>
\```
**Expected**: <what should happen>
### 2. <Action>: <description>
...
## Pass Criteria
- All steps marked PASS
- <additional criteria>
```
Key conventions:
- YAML-free, pure Markdown
- Each step has `bash` block + `Expected` block
- `ss` = `skillshare`, `~` = ssenv-isolated HOME
- Runbook can be executed by the `cli-e2e-test` skill
If the feature does not meet the criteria above, skip this step.
### Step 7: Stage and Report
1. List all created/modified files
2. Confirm each acceptance criterion is met with test evidence
3. Remind user to run `update-docs` if the feature affects CLI flags or user-visible behavior
## Rules
- **Test-first** — always write failing test before implementation
- **Minimal code** — only write what's needed to pass tests
- **Follow patterns** — match existing code style in each package
- **3-strike rule** — if a test fails 3 times after fixes, stop and report what's blocking
- **No docs** — this skill writes code only; use `update-docs` for documentation
- **No changelog** — use `changelog` skill for release notes
- **Spec ambiguity** — ask the user rather than guessing
章节与文件索引
按说明文件中的顺序排列。
第 1 步:了解需求
第 2 步:识别受影响的文件
第 3 步:首先编写失败的测试(红色)
第 4 步:实施(绿色)
第 5 步:重构和验证
文件/命令 -> specs/my-feature.md · update-docs · changelog · testutil.Sandbox · cmd/skillshare/ · internal/ · internal/ui · main.go
内容校验值 -> 695d865af8ea
当前原文的自动摘译,尚未人工审校。
第 1 步:了解需求
如果 $ARGUMENTS 是文件路径: 读取规范文件 提取接受标准和边缘情况 识别受影响的包 如果 $ARGUMENTS 是描述:
第 2 步:识别受影响的文件
列出将创建或修改的所有文件:显示文件列表并继续。如果范围不清楚,请询问用户。
第 3 步:首先编写失败的测试(红色)
使用
testutil.Sandbox编写集成测试:验证测试失败:第 4 步:实施(绿色)
编写最少的代码以使测试通过:遵循
cmd/skillshare/和internal/中的现有模式使用internal/ui进行终端输出(颜色、旋转器、框)添加用于改变命令的oplog工具:如果有新命令,则在main.go命令映射中注册命令第 5 步:重构和验证
清理代码,同时保持测试绿色运行全面的质量检查:修复任何格式或 lint 问题