oh-my-imagicma

v0.1.12

Published

5 days ago

OpenCode Plugin with Ralph Loop - Self-referential development loop until completion

0High
0Medium
0Low

jjvvv

opencode plugin ralph-loop ai llm

Oh My Imagicma

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

Features

ibuild-omega primary agent (default) - 顶级全栈交付 Agent，默认启用
ibuild-lite primary agent (optional) - 轻量工程执行 Agent（默认隐藏，可在配置中启用）
ibuild-nova primary agent (optional) - 下一代全栈交付 Agent（默认隐藏，可在配置中启用）
igen-lite subagent - 单子代理文档链路（mode=minimal|extended）
/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
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
refresh_all_logs() - Snapshot plugin/process-compose logs to .opencode/logs/<timestamp>/
get_latest_lsp_diagnostics(file_path) - Get latest LSP diagnostics (single file or cached latest)
architect(task, relevant_files, include_git_diff, responsibility, relevant_git_commits, relevant_integrations) - Architecture/debug/plan analysis in isolated sub-session
run_test(test_plan, relevant_technical_documentation, target_url?, default_screen_width, default_screen_height) - Structured test execution orchestration in isolated sub-session
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 里已定义同名命令，将不会被覆盖）。
默认会注入 agent.ibuild-omega 和 agent.igen-lite；agent.ibuild-lite 与 agent.ibuild-nova 默认隐藏，可在配置中启用。若 default_agent 当前未设置，会自动设为 ibuild-omega。 ibuild-lite 系统提示词维护入口：src/agents/ibuild-lite.md。 ibuild-omega 系统提示词维护入口：src/agents/ibuild-omega.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:

The agent works on the provided task
When the session goes idle, the system checks if the completion promise was output
If not complete, the agent is prompted to continue
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"]
)

Dependency Changes (packager_tool is temporarily hidden)

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

包管理器决策顺序：

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

Database / SQL

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

说明：

create_postgresql_database_tool 仅做检测与引导，不会自动创建云数据库。
execute_sql_tool 在 production 环境只允许只读 SQL（SELECT/WITH/EXPLAIN）。
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)
refresh_all_logs()

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

<dir>/process-compose.yaml
<dir>/process-compose.yml
<dir>/.imagicma/process-compose.yaml
<dir>/.imagicma/process-compose.yml
<dir>/.opencode/process-compose.yaml
<dir>/.opencode/process-compose.yml

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

示例配置：

version: "0.5"
log_location: ".opencode/logs/process-compose.log"
processes:
  web:
    command: "pnpm dev"
    working_dir: "."
    environment:
      PORT: "5001"

依赖说明：

restart_workflow / stop_workflow / refresh_all_logs 需要系统安装 process-compose
缺失时工具会返回 missing_dependency，不会自动安装

LSP Diagnostics

get_latest_lsp_diagnostics(file_path="src/index.ts")
get_latest_lsp_diagnostics()

Analysis / Testing / Docs

architect(task="Review this refactor", relevant_files=["src/index.ts"], include_git_diff=true, responsibility="evaluate_task")
run_test(test_plan="[Browser] ...", relevant_technical_documentation="...", target_url="http://127.0.0.1:3000", default_screen_width=1280, default_screen_height=720)
search_docs(query="workflow logs")

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": {
    "ibuild-lite": {
      "enabled": false
    },
    "ibuild-nova": {
      "enabled": false
    },
    "ibuild-omega": {
      "enabled": true,
      "set_as_default": true
    },
    "igen-lite": {
      "enabled": true
    }
  },
  "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

Create src/agents/<agent-name>.md (front matter + system prompt).
Import and register it in src/agents.ts by adding it to BUILTIN_AGENT_MARKDOWN_SOURCES.
Configure it in .opencode/oh-my-imagicma.json under agents.<agent-name>.

Troubleshooting

安装后看不到命令？

确认已把 "oh-my-imagicma" 加到 ~/.config/opencode/opencode.json 的 plugin 数组里，并重启 OpenCode
检查 .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）
LIVE_PREVIEW_BACKEND_URL（默认 http://127.0.0.1:9000）
LIVE_PREVIEW_INTERNAL_TOKEN（默认 imagicma-internal-dev-token）
LIVE_PREVIEW_DEFAULT_TARGET_URL（默认 http://127.0.0.1:3000）
LIVE_PREVIEW_LOOPBACK_PREVIEW_DOMAIN（可选；当目标为 localhost/127.0.0.1:端口 时，映射为 <端口>.<该域名>）
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

Publishing

登录 npm（若未登录）：
```
npm login
```
按提示输入 npm 用户名、密码和邮箱（或使用 2FA）。

确认版本：在 package.json 里改好 version，或使用：

npm version patch   # 0.1.0 -> 0.1.1
npm version minor   # 0.1.0 -> 0.2.0
npm version major   # 0.1.0 -> 1.0.0

发布：
```
npm publish
```
发布前会自动执行 prepublishOnly（clean + build），因此会先构建再上传。

首次发布前请确认 npmjs.com 上还没有同名包 oh-my-imagicma，否则需要换包名或使用 scope（如 @your-username/oh-my-imagicma）。

License

MIT