跳到主要内容
版本：0.3.x(Latest)

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

当前检查项如下：

检查项最低版本说明
Go1.25.0后端、工具链和WASM插件构建使用的Go工具链
Node.js20.19.0前端开发和构建所需的Node.js运行时
pnpm10.0.0前端依赖管理工具
Vite7.3.1项目本地前端构建工具，缺失时先执行make env.setup
Playwright1.58.2E2E测试运行器，缺失时先执行make env.setup
PostgreSQL14.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.cgoEnabledfalse是否启用CGO
build.outputDirtemp/output构建产物输出路径，相对于仓库根目录
build.binaryNamelina主框架二进制文件名

插件构建模式通过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.namelinapro镜像名称，构建时会在前面拼接registry前缀
image.tagdev默认标签，留空时根据git信息自动推导
image.registry空远端仓库前缀，例如ghcr.io/linaproai
image.pushfalse是否默认推送，命令行push=1可覆盖本次执行
image.baseImagealpine:3.22运行时基础镜像
image.dockerfilehack/docker/DockerfileDockerfile路径，相对于仓库根目录

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的资源软链。LinaPro把项目规范、技能和提示词统一维护在仓库标准位置，再通过软链适配不同工具自己的项目路径。

统一来源作用典型桥接示例
AGENTS.md项目顶层规范入口CLAUDE.md、GEMINI.md、QWEN.md
.agents/skills项目内置AI技能.claude/skills、.goose/skills、.augment/skills
.agents/prompts项目命令和提示词目录.claude/commands、.codex/prompts、.cursor/commands

这样做的目标是让团队只维护一份规范和一套技能，同时兼容开发者习惯使用的不同AI Coding工具。原生支持AGENTS.md或.agents/skills的工具会被识别为原生支持，命令只展示状态，不会重复创建不必要的软链。

这些命令只管理自己创建的软链；移除命令不会删除真实目录或文件，也不会移除指向外部目标的非托管软链。遇到已存在但目标不一致的软链时，通常需要传入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，聚合入口会跳过该资源并在汇总中说明原因。聚合入口适合个人开发环境初始化；如果要批量处理多个工具，使用后面的agents.<resource>.<action>命令。

将支持的智能体项目技能目录软链到统一来源.agents/skills。不传agent时，非交互环境会输出支持状态和提示；交互式终端会进入选择流程。支持agent=<name|all|csv>批量处理多个智能体。

技能目录承载的是项目内置能力，例如openspec-*、lina-review、lina-feedback、lina-e2e、frontend-design等。工具完成软链后，这些技能会按各自触发规则参与后续开发、审查和测试工作。

# 查看技能软链状态
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

移除由agents.skills.link管理的技能目录软链。非交互环境必须显式传入agent=<name|all|csv>；交互式终端可以从当前已托管软链中选择。

make agents.skills.unlink agent=claude-code
make agents.skills.unlink agent=all

将支持的智能体命令或提示词目录软链到.agents/prompts/下的规范来源。当前主要用于把.agents/prompts/opsx桥接到各工具自己的命令目录，例如.claude/commands/opsx、.cursor/commands/opsx、.codex/prompts/opsx或.gemini/commands/opsx。

提示词目录解决的是“同一套项目命令如何在不同工具里被调用”的问题。例如opsx工作流可以在支持命令目录的工具中保持一致入口，而不需要为每个工具复制一份命令文件。

# 查看提示词软链状态
make agents.prompts.link

# 为指定智能体创建提示词软链
make agents.prompts.link agent=codex

# 批量创建提示词软链
make agents.prompts.link agent=claude-code,codex,cursor,gemini-cli

移除由agents.prompts.link管理的提示词目录软链，不删除真实提示词目录。

make agents.prompts.unlink agent=codex
make agents.prompts.unlink agent=all

将支持的智能体私有规则文件软链到根目录AGENTS.md。例如，claude-code对应CLAUDE.md，gemini-cli对应GEMINI.md，qwen-code对应QWEN.md，junie对应.junie/guidelines.md。原生读取AGENTS.md的智能体只会在状态中展示，不需要创建软链。

AGENTS.md本身是项目顶层规范入口。它保留项目定位、强制触发场景和规则加载门禁；被它显式引用的.agents/rules/*.md承载更细的领域规则。开发插件时，插件目录还可以提供apps/lina-plugins/<plugin-id>/AGENTS.md作为本地规范入口，在该插件目录内覆盖全局规范中冲突的规则。

# 查看 AGENTS.md 规则文件软链状态
make agents.md.link

# 为指定智能体创建规则文件软链
make agents.md.link agent=claude-code

# 为所有可软链的智能体创建规则文件软链
make agents.md.link agent=all

移除由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