Oh My Imagicma

A minimal OpenCode plugin with Ralph Loop - self-referential development loop until task completion.

Features

• Markdown-driven built-in agents - 启动时自动扫描打包后的 src/agent/**/*.md 与 src/agents/**/*.md，新增 agent 只需新增 markdown 文件
• Markdown-driven built-in skills - 启动时自动将打包后的 src/skills/*/SKILL.md 注入到原生 config.skills.paths，行为与全局/项目 .opencode/skills 完全一致
• Built-in skills include style, ai-feature and spec-generator - style 用于生成风格指南，ai-feature 用于在 imagicma-template Hono 项目里按统一网关架构生成 AI 能力，spec-generator 用于基于项目画像分阶段生成 requirements、design、tasks 三件套
• Built-in agents include designer, refine, e2e-testing and related subagents - designer 适合从需求到前端界面的完整设计流程，e2e-testing 是公开可选的测试编排 subagent，默认按“能力 + 风险 + 用户旅程”拆测试主线
• /ralph-loop - Start a self-referential development loop that continues until task completion
• /ulw-loop - Start an ultrawork loop that continues until task completion
• /cancel-ralph - Cancel the currently active Ralph Loop
• search_codebase(query, search_glob_patterns) - Use a sub-session to analyze repo snapshots with long context; prefer it for semantic codebase questions, not regex-style lookup
• snapshot_runtime_logs() - Collect runtime signals from .imagicma/runtime/* and .imagicma/process-compose.log into .imagicma/log-snapshots/<timestamp>/
• query_runtime_logs(...) - Query structured browser, network, and workflow runtime signals
• Dependency management via shell (pnpm / npm) - packager_tool is temporarily not exposed
• create_postgresql_database_tool() - Detect DB env readiness and return setup guidance
• check_database_status() - Verify DB connectivity via psql (or TCP fallback)
• execute_sql_tool(sql_query, environment) - Execute SQL with production read-only guard
• view_env_vars(type, environment, keys) - View env values or secret existence from .env*
• set_env_vars(input) - Set/delete env keys in .env*
• restart_workflow(name, workflow_timeout, bootstrap_if_missing) - Restart a process defined in process-compose.yaml (auto-bootstrap manifest by default, supports common aliases like dev -> web)
• stop_workflow(scope, name, workflow_timeout) - Stop one process or stop all process-compose managed services
• snapshot_runtime_logs() - Snapshot runtime/plugin/process logs to .imagicma/log-snapshots/<timestamp>/
• query_runtime_logs() - Query live/runtime structured logs with source and process filters
• lsp_* - Full LSP tool chain for diagnostics, navigation, references, and rename workflows
• run_test(testPlan, relevantTechnicalDocumentation, targetUrl?, defaultScreenWidth, defaultScreenHeight, maxIterations?) - Run one explicit single-flow product test directly through verify_product; it is not a product-wide planner and returns testingPlan, live progress updates, final summary, DevTools-backed browser evidence, and runtime evidence
• inspect_page_semantics(url, defaultScreenWidth?, defaultScreenHeight?, focusHints?) - Read-only page semantics probe for false-negative review; returns the final URL, title, visible headings/text blocks, visible interactive elements, key text matches, and a screenshot path
• search_docs(query) - Local project docs search (README*, docs/**/*, **/*.md|mdx)
• memory_search / memory_get / memory_add / memory_profile_get / memory_profile_rebuild - 持久记忆检索、写入与画像查询/重建（含 chat 预取注入、compaction 兜底注入、自动脱敏候选捕获）

Installation

# Install the plugin
bun add oh-my-imagicma
# or
npm install oh-my-imagicma

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": ["oh-my-imagicma"]
}

提示：本插件会在启动时通过 OpenCode 的 config.command 自动注册 /ralph-loop、/ulw-loop、/cancel-ralph 三个命令（如果你在 opencode.json 里已定义同名命令，将不会被覆盖）。

默认会自动发现并注入打包内 src/agent/**/*.md 与 src/agents/**/*.md 下的所有 agent markdown。 同时会自动发现并注入打包内 src/skills/*/SKILL.md 下的所有内置 skills，注入方式是原生 skills.paths，不是插件私有格式。 如果用户已经在 .opencode/skills、.claude/skills、.agents/skills 或已有 config.skills.paths 中定义了同名 skill，则始终以用户本地定义为准，插件内置 skill 会自动跳过。 若未显式设置 default_agent，插件不会代替 OpenCode 选默认值，最终会回退到 OpenCode 原生的 build。 designer 系统提示词维护入口：src/agents/designer.md。 e2e-testing 系统提示词维护入口：src/agents/e2e-testing.md，作为公开可选的测试编排 agent 使用。 devtools-browser-verifier 系统提示词维护入口：src/agents/devtools-browser-verifier.md，仅供 verify_product 内部调用。 page-semantics-inspector 系统提示词维护入口：src/agents/page-semantics-inspector.md，仅供 inspect_page_semantics 内部调用。 内置 skill 维护入口：src/skills/<name>/SKILL.md。 当前公开内置 skill 包括：style、ai-feature、spec-generator。 测试体系长期规范沉淀：docs/testing-architecture.md。

Usage

Ralph Loop

Start a loop that continues until the task is complete:

/ralph-loop "Build a REST API with authentication"
/ralph-loop "Refactor the payment module" --max-iterations=50
/ralph-loop "Fix all TypeScript errors" --completion-promise=ALL_FIXED

How it works:

1. The agent works on the provided task
2. When the session goes idle, the system checks if the completion promise was output
3. If not complete, the agent is prompted to continue
4. This repeats until:
   • The completion promise is detected: <promise>DONE</promise>
   • Maximum iterations reached (default: 100)
   • User cancels with /cancel-ralph

Ultrawork Loop

Start an ultrawork loop that runs at maximum intensity until completion:

/ulw-loop "Build a REST API with authentication"
/ulw-loop "Refactor the payment module" --max-iterations=50
/ulw-loop "Fix all TypeScript errors" --completion-promise=ALL_FIXED

Cancel Ralph Loop

/cancel-ralph

search_codebase Tool

search_codebase(
  query="Where is session idle handling implemented?",
  search_glob_patterns=["src/**/*.ts", "README.md"]
)

search_codebase 是长上下文代码语义分析工具，适合回答“某能力在哪实现”“某路由/文案/交互入口来自哪里”这类跨文件问题；它不是 rg 替代，也不应该拿来扫描运行时工件或历史测试产物。工具默认会跳过 .imagicma/runtime/、.imagicma/diagnostics/ 和 .imagicma/log-snapshots/。

Dependency Changes (packager_tool is temporarily hidden)

# install
pnpm add express lodash
# fallback
npm install express lodash

包管理器决策顺序：

1. 目标目录存在 package-lock.json 时优先 npm
2. 否则优先 pnpm
3. pnpm 不可用时回退 npm

Database / SQL

create_postgresql_database_tool()
check_database_status()
execute_sql_tool(sql_query="select now();", environment="development")

说明：

1. create_postgresql_database_tool 仅做检测与引导，不会自动创建云数据库。
2. execute_sql_tool 在 production 环境只允许只读 SQL（SELECT/WITH/EXPLAIN）。
3. check_database_status 返回 not_configured 时，默认建议直接走 SQLite（default_runtime: sqlite），避免在未配置 DATABASE_URL 时反复卡在 Postgres。

Env Vars

view_env_vars(type="all", environment="shared")
set_env_vars(input={operation:"set", environment:"development", values:{API_BASE_URL:"https://example.com"}})

Workflow / Logs

restart_workflow(name="web", workflow_timeout=30, bootstrap_if_missing=true)
stop_workflow(scope="process", name="dev", workflow_timeout=30)
stop_workflow(scope="all", workflow_timeout=30)
snapshot_runtime_logs()
query_runtime_logs(sources=["process_states", "process_tail_lines"], processName="web")

运行时信号源优先来自 .imagicma/runtime/*；process-compose daemon 日志仅作为内部兜底。显式诊断包固定写入 .imagicma/diagnostics/<snapshotId>/。

工作流配置文件从 worktree 根目录向下 BFS 搜索子目录（最大深度 5 层），对每个目录按以下顺序检查：

1. <dir>/process-compose.yaml
2. <dir>/process-compose.yml
3. <dir>/.imagicma/process-compose.yaml
4. <dir>/.imagicma/process-compose.yml
5. <dir>/.opencode/process-compose.yaml
6. <dir>/.opencode/process-compose.yml

广度优先搜索确保更浅的目录优先匹配，例如根目录的配置优先于 infra/ 子目录的配置。搜索时自动跳过以 . 开头的目录（.git 等），并通过 git check-ignore 过滤所有 .gitignore 中声明的目录（如 node_modules、dist、build、vendor 等）。若 git 不可用则 fallback 到最小硬编码跳过列表。

示例配置：

version: "0.5"
processes:
  web:
    command: "pnpm dev"
    working_dir: "."
    environment:
      PORT: "5001"

依赖说明：

1. restart_workflow / stop_workflow 需要系统安装 process-compose
2. snapshot_runtime_logs / query_runtime_logs 会尽力收集插件日志与 runtime 工件；若缺少 process-compose 或 workflow manifest，只会缺失进程状态与 per-process tail，并通过 warnings 明确提示
3. 缺失依赖时不会自动安装

LSP Diagnostics

lsp_diagnostics(file_path="src/index.ts")
lsp_goto_definition(file_path="src/index.ts", line=10, character=5)
lsp_find_references(file_path="src/index.ts", line=10, character=5)
lsp_symbols(file_path="src/index.ts")
lsp_prepare_rename(file_path="src/index.ts", line=10, character=5)
lsp_rename(file_path="src/index.ts", line=10, character=5, new_name="updatedName")

Analysis / Testing / Docs

run_test(testPlan="验证首页到 Routes 页的主流程是否可用。需要确认首页能正常加载，点击 Routes 导航入口后能进入 /routes，并且页面正文包含 routes 文案，没有新的 runtime error。", relevantTechnicalDocumentation="应用使用本地预览地址，导航入口文本为 Routes。", targetUrl="http://127.0.0.1:3000", defaultScreenWidth=1280, defaultScreenHeight=720, maxIterations=3)
inspect_page_semantics(url="http://127.0.0.1:3000/environment", focusHints=["当前温度", "风速", "气压", "预警"])
search_docs(query="workflow logs")

run_test 是对外正式的单 flow 页面/流程验收入口。它返回结构化 JSON；自然语言 testPlan 会被当作一条明确主线直接交给 verify_product 执行，verify_product 内部通过专用 DevTools 浏览器执行器完成页面交互与证据采集。若目标是“全流程 / 全功能 / 覆盖主要场景”，应改用 e2e-testing 先拆成多轮 run_test。核心字段包括：

测试规划默认遵循内置 testing skill：先按“能力 + 风险 + 用户旅程”识别候选主线，再把每条主线写成合格的单 flow testPlan。页面存在性检查只适合 smoke 或模块完整性验收，不再默认代表主要覆盖。

当用户说“回归测试”“走一遍”“整体测一遍”时，默认应该进入 e2e-testing 拆主线，再逐轮调用 run_test；这类请求默认不是“检查仓库里是否存在 Playwright/Jest/Vitest 测试套件”。

当 run_test 因“元素未找到 / browser step failed / 首轮 503 后恢复”这类弱信号失败时，不要只看截图。默认应先按 testing skill 的 Failure Triage 规则处理：优先用页面快照 / DOM 语义和代码上下文复核，再决定是否保留失败或判成疑似假阴性。为此插件提供了只读工具 inspect_page_semantics(...)。

{
  "status": "success|failure|unable|blocked|skipped|error",
  "summary": "string",
  "testOutput": "string",
  "runId": "string",
  "subagentId": "string",
  "executionMode": "direct|subagent",
  "browserEngine": "devtools",
  "coverageSummary": {
    "total": 0,
    "verified": 0,
    "partiallyVerified": 0,
    "blocked": 0,
    "unsupported": 0,
    "failed": 0
  },
  "items": [],
  "steps": [],
  "screenshotPaths": [],
  "browser": {
    "checked": true,
    "currentUrl": "string",
    "pageErrors": [],
    "consoleErrors": [],
    "networkFailures": [],
    "httpErrors": [],
    "screenshots": []
  },
  "app": {
    "checked": true,
    "launchId": "string",
    "errorSignatures": [],
    "matchedLogLines": []
  }
}

说明：

1. run_test 会把本次输入、live updates、最终 JSON 结果和证据引用写到 .imagicma/runtime/run-test/<runId>/。
2. status=blocked 表示服务未就绪、前置条件缺失或请求超出当前验证能力；status=failure 表示真实验证已经执行，但覆盖项失败或证据不足。
3. direct 模式下 subagentId 会为空；底层浏览器执行器仍可能通过内部子会话完成单项验证。
4. 如果 testPlan 是“做一轮端到端测试 / 全流程验收 / 验证当前项目主要场景”这类泛化请求，run_test 会返回 unable 并提示改用 e2e-testing。
5. 如果一个 testPlan 同时混入搜索、创建、审批、主题切换等多种独立原型，run_test 也会拒绝并要求先拆成多轮。
6. 如果你只想验证单条页面或单个用户流，请在 testPlan 中写明真实交互、终态和关键按钮，而不只是“页面能打开”。

Notes

• 以下能力已直接复用 OpenCode 内置工具，不在插件中重复实现：task（start_subagent）、question（user_query/request_env_var）、websearch（do_web_search）、webfetch（web_fetch）。

Configuration

Create a config file at .opencode/oh-my-imagicma.json (project) or ~/.config/opencode/oh-my-imagicma.json (user):

{
  "agents": {
    "designer": {
      "enabled": true,
      "set_as_default": true
    },
    "refine": {
      "enabled": true,
      "set_as_default": false
    }
  },
  "ralph_loop": {
    "enabled": true,
    "default_max_iterations": 100,
    "state_dir": ".imagicma/ralph-loop.local.md"
  },
  "lite_oneshot": {
    "enabled": true,
    "max_attempts": 12,
    "stagnation_threshold": 3,
    "auto_log_snapshots": true
  },
  "memory": {
    "enabled": true,
    "query_trigger": "chat_message_and_compaction",
    "recovery_query": "latest architecture decisions, constraints, and pending tasks",
    "recovery_top_k": 6,
    "chat_query_top_k": 6,
    "chat_query_timeout_ms": 1800,
    "auto_capture_confidence": 0.72,
    "auto_capture_min_length": 30,
    "auto_capture_skip_synthetic": true,
    "auto_capture_redaction_enabled": true,
    "auto_capture_redaction_level": "balanced",
    "auto_capture_consent_mode": "implicit_private",
    "profile_enabled": true,
    "profile_scope": "MERGED",
    "profile_refresh_if_stale": true,
    "profile_top_k": 6,
    "compaction_query_use_latest_user": true,
    "compaction_query_history_limit": 20,
    "injection_reference_boundary": true,
    "injection_dedupe": true
  },
  "disabled_hooks": []
}

Memory 配置说明

• memory.query_trigger：
  • chat_message_and_compaction：在 chat.message 预取 context/profile 并缓存，experimental.chat.system.transform 注入；session.compacted 保留兜底。
  • compaction_only：仅在 session.compacted 阶段注入。
• memory.auto_capture_consent_mode 默认 implicit_private；设为 disabled 时不做自动候选捕获。
• candidate scope 规则：
  • implicit_private：插件传 USER_PRIVATE
  • 其他模式：插件不传 scope，由 memory-service 决策
• memory.auto_capture_redaction_* 默认开启平衡脱敏（token/secret/password/jwt/bearer/email/mobile）。
• memory.profile_* 控制画像查询与刷新策略；画像接口失败时会降级为仅注入 context，不阻断主流程。
• memory.injection_dedupe=true 时，会对 system.transform 与 session.compacted 注入做跨链路去重，避免重复上下文。

Memory 必填环境变量

• IMAGICMA_API_URL（memory internal API 基地址，默认 http://127.0.0.1:9000/api）
• MEMORY_INTERNAL_TOKEN（必填；memory internal API 鉴权）
• MEMORY_INTERNAL_TIMEOUT_MS（可选，默认 8000）
• MEMORY_INTERNAL_MAX_RETRIES（可选，默认 1，最大 3）

Add a new agent quickly

1. Create src/agents/<agent-name>.md (front matter + system prompt).
2. Restart OpenCode or reload the plugin so the packaged markdown directory is scanned again.
3. Configure it in .opencode/oh-my-imagicma.json under agents.<agent-name> only if you need to override enablement or set it as explicit default.
4. 内置 e2e-testing 是公开可选的测试编排 subagent，默认依赖内置 testing skill，适合把多轮测试执行、过程播报与故障归因从主对话上下文中拆出去。

兼容性说明：当前内置 agent markdown 只使用 OpenCode 原生 frontmatter，设计目标是可直接搬到 .opencode/{agent,agents}。新增 agent 时，优先使用 permission:，不要再依赖插件私有 frontmatter。

Add a new skill quickly

1. Create src/skills/<skill-name>/SKILL.md.
2. Use OpenCode-native skill frontmatter only:
   • name
   • description
   • optional fields such as license / compatibility / metadata
3. Keep the directory name and frontmatter name identical, matching OpenCode's native skill convention.
4. If the skill needs reference files, place them in the same skill directory or its subdirectories.
5. Run local verification after build/restart to confirm the skill appears in /config.skills.paths and /skill.

兼容性说明：内置 skills 不走插件私有格式，而是通过插件把 src/skills/*/SKILL.md 对应目录注入到原生 config.skills.paths。运行时仍由 OpenCode 原生 skill loader 负责发现、权限控制与内容加载。若用户已在 .opencode/skills、.claude/skills、.agents/skills 或已有 config.skills.paths 中定义同名 skill，则用户本地定义优先，插件内置 skill 会自动跳过。

Troubleshooting

安装后看不到命令？

1. 确认已把 "oh-my-imagicma" 加到 ~/.config/opencode/opencode.json 的 plugin 数组里，并重启 OpenCode
2. 检查 .opencode/oh-my-imagicma.json 或 ~/.config/opencode/oh-my-imagicma.json：
   • ralph_loop.enabled 不能是 false
   • disabled_hooks 里不要包含 "ralph-loop"

Tool 环境变量

• SEARCH_CODEBASE_MAX_FILES（默认 120）
• SEARCH_CODEBASE_MAX_FILE_BYTES（默认 50000）
• SEARCH_CODEBASE_MAX_TOTAL_BYTES（默认 600000）
• DATABASE_CHECK_TIMEOUT_MS（默认 10000）
• DATABASE_SQL_TIMEOUT_MS（默认 30000）
• PROCESS_COMPOSE_BOOT_TIMEOUT_MS（默认 20000）
• PROCESS_COMPOSE_COMMAND_TIMEOUT_MS（默认 30000）
• PROCESS_COMPOSE_LOG_TAIL_LINES（默认 200）
• ARCHITECT_TIMEOUT_MS（默认 120000）
• RUN_TEST_TIMEOUT_MS（默认 180000）
• SEARCH_DOCS_MAX_RESULTS（默认 20）
• IMAGICMA_API_URL（默认 http://127.0.0.1:9000/api；memory internal API 基地址）
• MEMORY_INTERNAL_TOKEN（必填；memory internal API 鉴权）
• MEMORY_INTERNAL_TIMEOUT_MS（默认 8000）
• MEMORY_INTERNAL_MAX_RETRIES（默认 1，最大 3）

Development

# Install dependencies
bun install

# Type check
bun run typecheck

# Build
bun run build

# Run tests
bun test

Local verification after plugin changes

推荐在每次修改 oh-my-imagicma 后都做一次本地验收，而不是只跑单测。

标准流程：

1. Build plugin:

   npm run build

2. Clear the old OpenCode Web listener:

   lsof -t -iTCP:4096 -sTCP:LISTEN -nP
   kill $(lsof -t -iTCP:4096 -sTCP:LISTEN -nP)
   kill -9 $(lsof -t -iTCP:4096 -sTCP:LISTEN -nP)

   不要改成 4097 或其他端口规避占用，先把 4096 清干净。
3. Restart web:

   opencode web --hostname 127.0.0.1 --port 4096

4. Poll until /config is ready:

   for i in {1..20}; do
     if curl -sf http://127.0.0.1:4096/config >/tmp/opencode-config.json; then
       break
     fi
     sleep 0.5
   done
   jq '{plugin,skills,default_agent}' /tmp/opencode-config.json

5. Verify changed objects:
   • Skills:

     curl -s --max-time 10 http://127.0.0.1:4096/skill > /tmp/opencode-skills.json

   • Agents:

     curl -s --max-time 10 http://127.0.0.1:4096/agent > /tmp/opencode-agents.json

推荐直接复用全局 skill $oh-my-imagicma-verify。该 skill 位于 /Users/alexliu/Project/skills/oh-my-imagicma-verify/SKILL.md，已经把这套流程、端口占用排查顺序，以及 /config、/skill、/agent 的核对方式沉淀好了。

Publishing

只保留一种发布方式：本地打包后直接部署到 helper，不再依赖 npm registry。

执行发布：

npm run deploy

只做预演、不真正修改服务器：

npm run deploy -- --dry-run

这条发布链路会自动完成：

• 执行 npm run build
• 在本地执行 npm pack 生成临时 tgz
• 通过 SSH 把 tgz 传到 helper
• 在 helper 上解包到固定目录：~/.config/opencode/plugins/oh-my-imagicma/current
• 自动把 ~/.config/opencode/config.json 的 plugin 设置为 file:///root/.config/opencode/plugins/oh-my-imagicma/current/dist/index.js
• 重启 opencode
• 通过 /config 和 /skill 验证运行中的插件已经从固定目录加载

说明：

• 默认目标机器就是 helper
• helper 会优先使用 OH_MY_IMAGICMA_HELPER_SSH；未设置时，会按 ssh-aliyun、ssh-ma.cn、ssh-ma-cn 的顺序查找你本地 shell 里可用的登录入口
• 这条链路不再要求先发布 npm 包，只要本地代码是对的，就能直接把服务器切到当前版本
• 若 SSH 提示 UNPROTECTED PRIVATE KEY / Permissions too open，OpenSSH 会忽略私钥并反复要密码甚至 Permission denied，请先：chmod 600 /path/to/your.pem

License

MIT