LinaPro项目提供了一套跨平台开发指令集。长期维护的任务编排集中在hack/tools/linactl中，以Go程序实现；根目录Makefile和make.cmd只是兼容入口，都会转发到底层linactl。因此同一套命令可以在macOS、Linux和Windows上使用，不再依赖GNU Make或POSIX Shell作为唯一入口。
平台说明
跨平台原生命令：所有平台都可以直接使用linactl：
cd hack/tools/linactl
go run . help
go run . status
go run . init confirm=init
go run . dev
macOS / Linux：可以继续使用根目录make兼容入口：
make help
make init confirm=init
make dev
Windows cmd.exe：使用项目根目录的make.cmd包装入口。在cmd.exe中会按可执行文件扩展名查找当前目录脚本，因此可直接省略.cmd后缀：
make dev
make build
make help
Windows PowerShell：需要加当前目录前缀。默认Windows环境下可写成.\make；如需避免与本机已安装的其他make命令混淆，可显式使用.\make.cmd：
.\make help
.\make init confirm=init
.\make dev
后续文档中所有make <指令>示例，都可以等价替换为cd hack/tools/linactl && go run . <指令>，参数格式保持一致。make兼容入口会转发常用变量；如果需要使用linactl专属参数，可直接调用go run . <指令>。
指令总览
| 指令 | 分类 | 说明 |
|---|---|---|
make env.check | 环境 | 检查本地开发工具、项目本地前端工具和PostgreSQL版本 |
make env.setup | 环境 | 安装前端依赖和Playwright Chromium浏览器及系统依赖 |
make dev | 开发服务 | 重启前后端开发服务器 |
make stop | 开发服务 | 停止前后端开发服务器 |
make status | 开发服务 | 查看前后端运行状态及日志路径 |
make build | 构建 | 完整构建前端、插件和后端二进制 |
make pack.assets | 构建 | 准备主框架嵌入所需的前端静态资源和manifest |
make wasm | 构建 | 构建所有或指定运行时WASM插件 |
make tidy | 构建 | 整理主框架、工具和插件相关Go模块依赖 |
make image | 镜像 | 构建生产Docker镜像 |
make image.build | 镜像 | 仅准备镜像产物，不执行Docker构建 |
make test | 测试 | 运行完整E2E测试套件 |
make test.go | 测试 | 运行Go单元测试 |
make test.host | 测试 | 只运行主框架自有E2E测试 |
make test.plugins | 测试 | 运行官方插件自有E2E测试 |
make test.scripts | 测试 | 运行工具脚本的单元与smoke测试 |
make i18n.check | 国际化 | 扫描运行时硬编码文案并校验语言包key覆盖 |
make plugins.init | 插件工作区 | 将官方插件子模块转换为普通目录 |
make plugins.install | 插件工作区 | 安装配置中的源码插件到apps/lina-plugins |
make plugins.update | 插件工作区 | 更新apps/lina-plugins中的源码插件 |
make plugins.status | 插件工作区 | 查看源码插件工作区状态 |
make agents | 智能体资源 | 为单个智能体一键创建或移除技能、提示词和AGENTS.md相关软链 |
make agents.skills.link | 智能体资源 | 将支持的智能体项目技能目录软链到.agents/skills |
make agents.skills.unlink | 智能体资源 | 移除由agents.skills.link管理的技能目录软链 |
make agents.prompts.link | 智能体资源 | 将支持的智能体命令或提示词目录软链到.agents/prompts/... |
make agents.prompts.unlink | 智能体资源 | 移除由agents.prompts.link管理的提示词目录软链 |
make agents.md.link | 智能体资源 | 将支持的智能体私有规则文件软链到根目录AGENTS.md |
make agents.md.unlink | 智能体资源 | 移除由agents.md.link管理的AGENTS.md规则文件软链 |
make init | 数据库 | 初始化数据库表结构和种子数据 |
make mock | 数据库 | 加载演示Mock数据 |
make release.tag.check | 发布治理 | 校验release tag与metadata.yaml中framework.version一致 |
make help | 其他 | 查看所有可用指令 |
环境管理
make env.check
检查本地开发环境是否满足默认开发工作流要求。该命令只读取工具版本和数据库连接信息，不修改工作区。除Vite和Playwright使用项目本地依赖外，PostgreSQL版本会通过apps/lina-core/manifest/config/config.yaml中的database.default.link连接数据库后查询。
make env.check
当前检查项如下：
| 检查项 | 最低版本 | 说明 |
|---|---|---|
Go | 1.25.0 | 后端、工具链和WASM插件构建使用的Go工具链 |
Node.js | 20.19.0 | 前端开发和构建所需的Node.js运行时 |
pnpm | 10.0.0 | 前端依赖管理工具 |
Vite | 7.3.1 | 项目本地前端构建工具，缺失时先执行make env.setup |
Playwright | 1.58.2 | E2E测试运行器，缺失时先执行make env.setup |
PostgreSQL | 14.0.0 | 通过database.default.link探测服务端版本 |
make env.setup
安装开发与E2E测试所需的前端依赖、Playwright Chromium浏览器和浏览器运行所需系统依赖。在首次克隆仓库或CI环境初始化时执行一次即可，后续通常不需要重复运行。
make env.setup
开发服务
make dev
重启后端和前端开发服务器。执行前会先校验命令参数中的backend_port、后端server.address和前端Vite proxy target是否一致，避免端口错配后才暴露为健康检查超时或接口错误。随后命令会停止已有服务，按插件模式决定是否构建WASM插件，准备前端静态资源，编译后端并等待两端健康检查通过。
make dev
# 强制主框架模式，跳过官方源码插件和 WASM 插件构建
make dev plugins=0
# 强制启用官方源码插件模式
make dev plugins=1
plugins=auto是默认模式：当apps/lina-plugins/中存在可用插件manifest时自动启用官方插件模式，否则使用主框架模式。直接调用linactl dev时还可以传入skip_wasm=true只跳过WASM构建步骤。
cd hack/tools/linactl
go run . dev skip_wasm=true
后端默认监听http://localhost:9120，前端开发服务器默认监听http://localhost:5666，管理工作台默认开发入口为http://localhost:5666/admin。运行日志分别写入temp/lina-core.log和temp/lina-vben.log。
make stop
停止后端和前端开发服务器，并清理残留PID文件。对于仍占用端口的僵尸进程，会强制终止。
make stop
make status
打印前后端当前的运行状态及日志文件路径，便于快速确认服务是否正常启动。
make status
输出示例：
+----------+---------+------------------------+-------+------------------------+--------------------+
| Service | Status | URL | PID | PID File | Log File |
+----------+---------+------------------------+-------+------------------------+--------------------+
| Backend | running | http://127.0.0.1:9120/ | 87739 | temp/pids/backend.pid | temp/lina-core.log |
| Frontend | running | http://127.0.0.1:5666/ | 87740 | temp/pids/frontend.pid | temp/lina-vben.log |
+----------+---------+------------------------+-------+------------------------+--------------------+
代码构建
make build
完整构建流程，依次执行：前端静态资源构建、嵌入到后端的静态资源和manifest资源准备、按插件模式构建动态WASM插件，最后编译后端主框架二进制。构建产物输出到temp/output/目录。
# 默认构建（当前平台）
make build
# 强制主框架模式，不构建官方源码插件
make build plugins=0
# 指定目标平台（交叉编译）
make build platforms=linux/amd64,linux/arm64
# 覆盖构建产物目录和二进制名称
make build output_dir=temp/release binary_name=linapro
# 覆盖配置文件
make build config=hack/config.yaml
# 开启详细日志
make build verbose=1
# 或
make build v=1
构建行为的默认值由仓库根目录的hack/config.yaml集中管理，命令行参数会覆盖文件中的对应字段。
build:
# 目标平台列表，使用goos/goarch格式，make build platforms=...可覆盖
platforms:
- "auto"
# 是否启用 CGO
cgoEnabled: false
# 构建产物输出路径，相对于仓库根目录
outputDir: "temp/output"
# 编译后生成的二进制文件名
binaryName: "lina"
| 字段 | 默认值 | 说明 |
|---|---|---|
build.platforms | ["auto"] | 目标平台列表，使用goos/goarch格式，auto表示linux/<当前架构>，make build platforms=...可覆盖 |
build.cgoEnabled | false | 是否启用CGO |
build.outputDir | temp/output | 构建产物输出路径，相对于仓库根目录 |
build.binaryName | lina | 主框架二进制文件名 |
插件构建模式通过plugins参数控制：
plugins值 | 说明 |
|---|---|
auto（默认） | 当apps/lina-plugins/存在可用插件manifest时启用官方源码插件模式 |
0 | 强制主框架模式，移除官方插件构建标签并跳过官方插件WASM构建 |
1 | 强制启用官方源码插件模式；如果插件工作区不可用，命令会快速失败 |
make wasm
单独构建运行时WASM插件。make wasm是兼容入口，默认把产物输出到temp/output/，支持使用p=<plugin-id>只构建指定插件，并可通过dry_run=true只检查可构建插件而不写产物。需要构建任意路径下的单个插件目录时，直接使用linactl wasm plugin_dir=<path>。
# 构建所有 WASM 插件
make wasm
# 只构建指定插件（plugin-id 为插件目录名）
make wasm p=my-plugin
# 只检查构建计划
make wasm dry_run=true
# 直接构建指定插件目录
cd hack/tools/linactl
go run . wasm plugin_dir=../../apps/lina-plugins/my-plugin out=../../temp/output
make pack.assets
准备主框架manifest资产，用于Go嵌入。该命令会刷新apps/lina-core/internal/packed/manifest/下的config、sql和i18n资源，通常由make build或make dev自动调用。需要单独检查或准备嵌入资源时可以手动执行：
make pack.assets
make tidy
整理主框架、开发工具和插件相关Go模块依赖，适合在升级依赖或初始化插件完整模式后执行：
make tidy
镜像编译
make image
完整的Docker镜像构建流程：先执行镜像构建预检，再执行make build生成所有构建产物，最后调用hack/tools/image-builder封装成镜像。镜像名称、标签、镜像仓库地址、基础镜像和插件构建模式等均通过参数配置。
# 使用默认配置构建镜像
make image
# 指定标签和镜像仓库
make image tag=v0.6.0 registry=ghcr.io/linaproai
# 构建后直接推送
make image tag=v0.6.0 registry=ghcr.io/linaproai push=1
# 多平台构建
make image platforms=linux/amd64,linux/arm64 tag=v0.6.0
# 覆盖运行时基础镜像并使用主框架模式
make image base_image=alpine:3.22 plugins=0
镜像构建的默认值同样由hack/config.yaml管理，命令行参数可覆盖本次执行。
image:
# 镜像名称，构建时拼接 registry 前缀
name: "linapro"
# 默认标签，留空时根据 git 信息自动推导
tag: "dev"
# 远端仓库前缀，例如 ghcr.io/linaproai
registry: ""
# 是否默认推送，push=1 可覆盖本次执行
push: false
# 运行时基础镜像
baseImage: "alpine:3.22"
# Dockerfile 路径，相对于仓库根目录
dockerfile: "hack/docker/Dockerfile"
| 字段 | 默认值 | 说明 |
|---|---|---|
image.name | linapro | 镜像名称，构建时会在前面拼接registry前缀 |
image.tag | dev | 默认标签，留空时根据git信息自动推导 |
image.registry | 空 | 远端仓库前缀，例如ghcr.io/linaproai |
image.push | false | 是否默认推送，命令行push=1可覆盖本次执行 |
image.baseImage | alpine:3.22 | 运行时基础镜像 |
image.dockerfile | hack/docker/Dockerfile | Dockerfile路径，相对于仓库根目录 |
make image.build
仅准备镜像构建的所有产物（等价于先执行make build并生成镜像构建上下文），不执行Docker build步骤。适用于需要手动检查产物或自定义镜像构建步骤的场景。
make image.build
测试管理
make test
运行完整的Playwright E2E测试套件。执行前请确保开发服务已通过make dev启动。支持通过scope参数缩小测试范围：
scope值 | 说明 |
|---|---|
full（默认） | 运行全部E2E测试 |
host | 仅运行主框架自有测试 |
plugins | 仅运行所有官方插件测试 |
plugin:<id> | 仅运行指定插件测试 |
make test
# 只运行主框架测试
make test scope=host
# 只运行指定插件测试
make test scope=plugin:multi-tenant
make test.go
运行所有受维护Go模块的单元测试，并默认启用竞态检测和详细日志。命令会先发现当前Go workspace中的模块，把有测试文件的包作为真实测试执行，把没有测试文件的包作为编译冒烟检查执行，并按模块输出汇总。支持通过plugins=0强制主框架模式，或通过race=false关闭竞态检测。
make test.go
make test.go plugins=0
make test.go race=false
make test.go verbose=false
make test.host
只运行主框架自有Playwright E2E测试，不要求初始化官方插件子模块。
make test.host
make test.plugins
运行官方插件自有Playwright E2E测试，执行前需要先初始化apps/lina-plugins/子模块。
make test.plugins
make test.scripts
运行跨平台仓库工具的单元和smoke检查，用于验证linactl、make.cmd等辅助入口的基本正确性。
make test.scripts
插件管理
apps/lina-plugins/目录用于存放官方插件，既可以是Git submodule，也可以通过插件工作区命令管理为源码插件。以下命令提供对插件工作区的完整生命周期管理：
make plugins.init
将apps/lina-plugins从Git submodule转换为普通插件目录，同时保留插件代码。转换后可以自由修改插件代码并提交变更，不再受submodule约束。
make plugins.init
make plugins.install
根据hack/config.yaml中的plugins.sources配置，将远端插件仓库中的指定插件克隆到apps/lina-plugins/。支持通过p=<plugin-id>只安装一个插件，通过source=<name>只处理指定来源。
# 安装所有配置的源码插件
make plugins.install
# 只安装指定插件
make plugins.install p=multi-tenant
# 强制覆盖已存在的插件目录
make plugins.install force=1
make plugins.update
更新apps/lina-plugins/中已配置的源码插件，拉取远端最新版本。有本地未提交改动的插件会被阻止更新，除非传入force=1。
make plugins.update
make plugins.update p=multi-tenant
make plugins.update force=1
make plugins.status
查看当前官方插件工作区状态，包括已配置的插件版本、本地变更和远端更新情况。
make plugins.status
I18N国际化
make i18n.check
扫描运行时可见的代码路径，检测未被纳入国际化体系的硬编码文案，并校验主框架和各插件运行时语言包的消息key覆盖情况。适合在提交新功能前进行i18n合规自查。
make i18n.check
AI工具集成
agents系列命令用于管理仓库内面向不同AI Coding Agent的资源软链。仓库以.agents/skills、.agents/prompts/和根目录AGENTS.md作为统一资源来源，再按不同工具的约定路径创建软链，例如.claude/skills、.codex/prompts/opsx、CLAUDE.md或GEMINI.md。
这些命令只管理自己创建的软链；移除命令不会删除真实目录或文件，也不会移除指向外部目标的非托管软链。遇到已存在但目标不一致的软链时，通常需要传入FORCE=1才会重建。
make agents
推荐使用的聚合入口。无参数且连接到交互式终端时，会先用方向键选择智能体，再选择link或unlink操作；在非交互环境中，通过agent=<name>指定单个智能体。聚合入口会对该智能体支持的所有资源类型执行同一操作，不支持agent=all或逗号列表。
# 交互式选择智能体和操作
make agents
# 为单个智能体创建所有可用资源软链
make agents agent=claude-code
# 移除单个智能体的托管软链
make agents agent=claude-code action=unlink
# 重建目标不一致的托管软链
make agents agent=claude-code force=1
如果智能体原生读取某类资源，例如原生读取AGENTS.md，聚合入口会跳过该资源并在汇总中说明原因。
make agents.skills.link
将支持的智能体项目技能目录软链到统一来源.agents/skills。不传agent时，非交互环境会输出支持状态和提示；交互式终端会进入选择流程。支持agent=<name|all|csv>批量处理多个智能体。
# 查看技能软链状态
make agents.skills.link
# 为指定智能体创建技能软链
make agents.skills.link agent=claude-code
# 为所有可软链的智能体创建技能软链
make agents.skills.link agent=all
# 重建目标不一致的技能软链
make agents.skills.link agent=claude-code force=1
make agents.skills.unlink
移除由agents.skills.link管理的技能目录软链。非交互环境必须显式传入agent=<name|all|csv>；交互式终端可以从当前已托管软链中选择。
make agents.skills.unlink agent=claude-code
make agents.skills.unlink agent=all
make agents.prompts.link
将支持的智能体命令或提示词目录软链到.agents/prompts/下的规范来源。当前主要用于把.agents/prompts/opsx桥接到各工具自己的命令目录，例如.claude/commands/opsx、.cursor/commands/opsx、.codex/prompts/opsx或.gemini/commands/opsx。
# 查看提示词软链状态
make agents.prompts.link
# 为指定智能体创建提示词软链
make agents.prompts.link agent=codex
# 批量创建提示词软链
make agents.prompts.link agent=claude-code,codex,cursor,gemini-cli
make agents.prompts.unlink
移除由agents.prompts.link管理的提示词目录软链，不删除真实提示词目录。
make agents.prompts.unlink agent=codex
make agents.prompts.unlink agent=all
make agents.md.link
将支持的智能体私有规则文件软链到根目录AGENTS.md。例如，claude-code对应CLAUDE.md，gemini-cli对应GEMINI.md，qwen-code对应QWEN.md，junie对应.junie/guidelines.md。原生读取AGENTS.md的智能体只会在状态中展示，不需要创建软链。
# 查看 AGENTS.md 规则文件软链状态
make agents.md.link
# 为指定智能体创建规则文件软链
make agents.md.link agent=claude-code
# 为所有可软链的智能体创建规则文件软链
make agents.md.link agent=all
make agents.md.unlink
移除由agents.md.link管理的规则文件软链。该命令不会删除手写的CLAUDE.md、GEMINI.md等真实文件。
make agents.md.unlink agent=claude-code
make agents.md.unlink agent=all
数据库
init和mock均会对数据库执行破坏性操作，因此要求显式传入confirm参数才能执行，防止误操作。
make init
初始化数据库的表结构（DDL）和系统必需的种子数据。命令读取apps/lina-core/manifest/config/config.yaml中的database.default.link，当前仅支持PostgreSQL 14+方言；sqlite:、mysql:或未知链接会在方言解析阶段快速失败，不会创建本地数据库文件或继续执行SQL。
# 仅初始化（保留现有数据）
make init confirm=init
# 重建数据库（清空后重新初始化）
make init confirm=init rebuild=true
如果PostgreSQL无法连接，命令会提示先启动PostgreSQL，并输出本地docker run示例。rebuild=true会先终止目标数据库连接，再执行DROP DATABASE IF EXISTS和CREATE DATABASE，只应在确认可以清空目标库时使用。
make mock
在make init完成之后，加载用于本地演示和开发验证的可选Mock数据。
make mock confirm=mock
其他
make help
打印默认可用的跨平台开发指令列表，输出按指令名称排序。linactl内部还注册了cli、cli.install、ctrl和dao等维护命令，默认帮助不会展示；只有直接执行go run . help --all时才会列出。
make help