Folio

folio

Bun monorepo 项目骨架，当前包含：

• apps/server：基于 Hono 的服务端应用
• packages/core：共享核心能力
• packages/cli：命令行入口，对外暴露 folio
• packages/claude-plugins/folio：Claude Code plugin

当前包结构：

apps/
  server/

packages/
  core/
  cli/
  claude-plugins/
    folio/

当前 workspace 匹配规则：

• apps/*
• packages/*

启动：

bun run server
bun run server:dev

本地联调：从添加 marketplace 到测试具体功能

1. 安装依赖

bun install

2. 启动本地 server

默认 dev 环境端口是 3000。

bun run server:dev

也可以显式指定环境和端口：

FOLIO_ENV=dev PORT=3000 bun run --cwd apps/server start:dev

用 health 接口确认服务已启动：

curl http://127.0.0.1:3000/health

预期返回类似：

{"success":true,"data":{"status":"ok"}}

3. 将本仓库作为本地 marketplace 添加到 Claude Code

仓库根的 marketplace 文件位于 .claude-plugin/marketplace.json，其中当前 plugin 为 folio@folio-plugins。

claude plugin marketplace add .
claude plugin install folio@folio-plugins --scope local

如果你只是想跳过 marketplace、直接本地加载 plugin，也可以使用：

claude --plugin-dir ./packages/claude-plugins/folio

4. 本地测试 CLI 能力

CLI 入口文件是 packages/cli/src/index.ts。下面示例默认连接本地 dev server。

先创建一个测试文本文件：

cat > /tmp/folio-demo.txt <<'EOF'
# Folio Demo

This is a local plugin test.
EOF

测试 txt2html：

bun run packages/cli/src/index.ts txt2html /tmp/folio-demo.txt

测试创建 item：

bun run packages/cli/src/index.ts --env dev items create --name demo --content-file /tmp/folio-demo.txt

测试列出 items：

bun run packages/cli/src/index.ts --env dev items list

测试获取单个 item：

bun run packages/cli/src/index.ts --env dev items get <id>

测试更新 item：

bun run packages/cli/src/index.ts --env dev items update <id> --name demo-updated --content "updated content"

测试删除 item：

bun run packages/cli/src/index.ts --env dev items delete <id>

如果你希望显式指定服务地址，也可以这样运行：

FOLIO_SERVER_BASE_URL=http://127.0.0.1:3000 bun run packages/cli/src/index.ts items list

5. 本地测试 plugin / marketplace 链路

安装完成后，可以在 Claude Code 中直接调用 plugin 提供的 skills，例如：

• /folio:txt2html
• /folio:items-list
• /folio:items-get
• /folio:items-create
• /folio:items-update
• /folio:items-delete
• /folio:create-item-from-text

推荐按下面顺序验证：

1. 先确保本地 server 仍在运行
2. 在 Claude Code 中执行 /folio:items-list，确认能连通本地服务
3. 执行 /folio:txt2html 或 /folio:create-item-from-text，确认 plugin -> CLI -> core 链路可用
4. 再执行 /folio:items-get、/folio:items-update、/folio:items-delete 验证完整 CRUD

6. 一组可直接复制的最小联调命令

bun install
bun run server:dev
curl http://127.0.0.1:3000/health
claude plugin marketplace add .
claude plugin install folio@folio-plugins --scope local
cat > /tmp/folio-demo.txt <<'EOF'
# Folio Demo

This is a local plugin test.
EOF
bun run packages/cli/src/index.ts txt2html /tmp/folio-demo.txt
bun run packages/cli/src/index.ts --env dev items create --name demo --content-file /tmp/folio-demo.txt
bun run packages/cli/src/index.ts --env dev items list

文档：

• docs/index.md
• docs/structure.md
• docs/development.md
• docs/plugin-design.md
• CLAUDE.md
• AGENTS.md